// 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.
Solo-native planning workflow. Use when asked to "plan", "brainstorm", "design", "create a plan", "I want to build", or "let's build". Runs a scout, opens a planner that is interactive through approach selection, creates Solo todos, then automatically executes and reviews through Solo subagents and scratchpads.
Start a fresh Solo Pi session from the current conversation. Use when asked to hand off, continue in a clean context, or run `/handoff <new prompt>`. Writes a Solo scratchpad summary of the important current-session context, then launches an interactive Solo agent in the same project with that handoff and the new prompt.
Write clear Solo todos that workers can execute without losing architectural intent. Use when asked to "create todos", "write todos", "break into tasks", "plan todos", or create work items from a plan. Ensures each todo has outcomes, examples, constraints, and verification criteria.
Read this skill before making git commits
Iterate on a PR until CI passes. Use when you need to fix CI failures, address review feedback, or continuously push fixes until all checks are green. Automates the feedback-fix-push-wait cycle.
Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, planning, writing, registration, and verification.
| 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. |
Parse pi session JSONL files into readable output. Sessions live in ~/.pi/agent/sessions/<project>/ as .jsonl files.
ls -t ~/.pi/agent/sessions/*<project>*/*.jsonl | head -10
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.
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"
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 | 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 |
| 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) |
--mode toc → scan the session, find interesting exchanges--mode turn --turn N → drill into specific exchanges--mode subagents → review delegated work and follow subagent session pathsSubagent 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
Read ${CLAUDE_SKILL_ROOT}/references/session-format.md only if custom parsing is needed.