| name | session-reader |
| description | 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. |
Read Pi Sessions
Parse pi session JSONL files into readable output. Sessions live in ~/.pi/agent/sessions/<project>/ as .jsonl files.
Step 1: Find the Session
ls -t ~/.pi/agent/sessions/*<project>*/*.jsonl | head -10
Step 2: Start with Table of Contents
Always start with toc to get a numbered map of the session:
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --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].
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path>
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --offset 5 --limit 3
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --search "error"
Step 4: Drill Into a Turn
See everything about a specific exchange — thinking, tool calls, tool results, costs:
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --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
--mode toc → scan the session, find interesting exchanges- Default (conversation) → read the human-readable flow
--mode turn --turn N → drill into specific exchanges--mode subagents → review delegated work and follow subagent session paths
Subagent Drill-Down
Subagent session files can be read with the same script:
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <subagent-jsonl-path> --mode toc
Session Format Reference
Read ${CLAUDE_SKILL_ROOT}/references/session-format.md only if custom parsing is needed.
