Session Reader

Documents

session-reader

Session Reader is an Agent Skill for documents published in the HazAT/pi-config repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/HazAT/pi-config/blob/HEAD/skills/session-reader/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/session-reader, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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].

# Full conversation (default mode)
uv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path>

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

# Search for specific topic
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:

# From --mode subagents output, grab the JSONL path
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.