# Session Reader

> Efficiently read and analyze pi agent session JSONL files. Use when asked to "read a session", "review a session", "analyze a session", "what happened in this session", "load session", "parse session", "session history", "go through sessions", or given a .jsonl session file path.

- **Type:** Skill
- **Install:** `agentstack add skill-hazat-pi-config-session-reader`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HazAT](https://agentstack.voostack.com/s/hazat)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HazAT](https://github.com/HazAT)
- **Source:** https://github.com/HazAT/pi-config/tree/main/skills/session-reader

## Install

```sh
agentstack add skill-hazat-pi-config-session-reader
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Read Pi Sessions

Parse pi session JSONL files into readable output. Sessions live in `~/.pi/agent/sessions//` as `.jsonl` files.

## Step 1: Find the Session

```bash
ls -t ~/.pi/agent/sessions/**/*.jsonl | head -10
```

## Step 2: Start with Table of Contents

Always start with `toc` to get a numbered map of the session:

```bash
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py  --mode toc
```

This prints a compact numbered list of every user exchange with timestamps and tools used.

## Step 3: Read the Conversation

Default mode — shows only user messages and assistant text responses. Tool calls are hidden but hinted at with `[used: tool1, tool2]`.

```bash
# Full conversation (default mode)
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py 

# Specific range
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py  --offset 5 --limit 3

# Search for specific topic
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py  --search "error"
```

## Step 4: Drill Into a Turn

See everything about a specific exchange — thinking, tool calls, tool results, costs:

```bash
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py  --mode turn --turn 7
```

## Mode Reference

| Mode | Shows | Use for |
|------|-------|---------|
| `conversation` | User + assistant text only (default) | Reading what happened |
| `toc` | Numbered exchange list | Navigation, finding the right turn |
| `turn` | Full detail for one exchange | Drilling into specifics |
| `issues` | Errors, failures, retries, user complaints | Finding what broke |
| `overview` | Metadata + exchange summaries | Quick session assessment |
| `full` | Everything including tool I/O | Deep debugging |
| `tools` | Tool calls and results only | Understanding agent actions |
| `costs` | Token usage and cost per turn | Cost analysis |
| `subagents` | Subagent task/status/cost/paths | Reviewing delegated work |

## Flags

| Flag | Effect |
|------|--------|
| `--offset N` | Skip first N exchanges |
| `--limit N` | Show at most N exchanges |
| `--turn N` | Exchange number to drill into (with `--mode turn`) |
| `--search TERM` | Filter exchanges containing TERM (case-insensitive) |
| `--max-content N` | Max chars per block (default: 3000, 0=unlimited) |

## Typical Workflow

1. `--mode toc` → scan the session, find interesting exchanges
2. Default (conversation) → read the human-readable flow
3. `--mode turn --turn N` → drill into specific exchanges
4. `--mode subagents` → review delegated work and follow subagent session paths

## Subagent Drill-Down

Subagent session files can be read with the same script:

```bash
# From --mode subagents output, grab the JSONL path
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py  --mode toc
```

## Session Format Reference

Read `${CLAUDE_SKILL_ROOT}/references/session-format.md` only if custom parsing is needed.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HazAT](https://github.com/HazAT)
- **Source:** [HazAT/pi-config](https://github.com/HazAT/pi-config)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hazat-pi-config-session-reader
- Seller: https://agentstack.voostack.com/s/hazat
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.