Read Pi Sessions
Parse pi session JSONL files into readable, structured output. Sessions live in ~/.pi/agent/sessions/<project>/ as .jsonl files.
Step 1: Identify the Session File
Resolve the session file path. Sessions are stored at:
~/.pi/agent/sessions/--<path-with-dashes>--/<timestamp>_<uuid>.jsonl
If the user provides a partial path or project name, find the file:
ls -t ~/.pi/agent/sessions/*<project>*/*.jsonl | head -5
Step 2: Start with an Overview
Always start with the overview to understand the session before diving deeper:
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --mode overview
This shows: session metadata (model, project, cost), turn count, and a summary of every turn with timestamps and tool calls used.
Step 3: Read Specific Content
Based on what's needed, use the appropriate mode:
| Goal | Command |
|---|---|
| See user/assistant conversation only | --mode conversation |
| See everything including tool I/O | --mode full |
| See what tools were called and results | --mode tools |
| Analyze token usage and costs | --mode costs |
| See subagent delegations with task/status/cost/paths | --mode subagents |
Controlling Output Size
For large sessions, use --offset and --limit to page through user turns:
# Skip first 3 user turns, show next 5
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --mode conversation --offset 3 --limit 5
Control content truncation with --max-content:
# Show full tool outputs (no truncation)
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --mode full --max-content 0
# Shorter previews (500 chars per block)
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --mode full --max-content 500
Step 3b: Drill into Subagent Sessions
When a session contains subagent calls, the --mode subagents output shows paths to each subagent's own JSONL session. Read those with the same script:
# Persistent artifact copy (always available)
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py ~/.pi/agent/sessions/<project>/subagent-artifacts/<hash>_worker.jsonl --mode overview
# Temp session file (may be cleaned up)
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py $TMPDIR/pi-subagent-session-<id>/run-0/<timestamp>.jsonl --mode overview
Subagent sessions use the exact same JSONL format. The overview and full modes all handle subagent data — they show inline summaries with agent, model, cost, duration, and status for each subagent run.
Step 4: Report Findings
When summarizing a session for the user, include:
- What was the goal — first user message intent
- What happened — key steps taken, tools used, decisions made
- Outcome — did it succeed? What was the final state?
- Notable issues — errors, retries, workarounds, wasted effort
- Cost — total spend and token usage
Session Format Reference
If you need to understand the raw JSONL format (for custom parsing), read:
${CLAUDE_SKILL_ROOT}/references/session-format.md
The critical thing to know: message content is nested at line.message.content, NOT line.content. Content is always an array of typed objects (text, toolCall, thinking). Tool results are separate message entries with role: "toolResult".