How do I install the Session Reader skill?

Run npx skillmds@latest add hazat/session-reader in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Session Reader safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Session Reader?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Session Reader free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Session Reader?

hazat (@hazat) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Session Reader by hazat — Agent Skill

Name: Session Reader
Author: hazat

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.

hazat a92f7c4 3 files · 42.3 KB Updated Sep 17, 2026

File contents

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.

---name: session-readerdescription: 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 SessionsParse pi session JSONL files into readable output. Sessions live in `~/.pi/agent/sessions/<project>/` as `.jsonl` files.## Step 1: Find the Session```bashls -t ~/.pi/agent/sessions/*<project>*/*.jsonl | head -10```## Step 2: Start with Table of ContentsAlways start with `toc` to get a numbered map of the session:```bashuv 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 ConversationDefault 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 <path># Specific rangeuv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --offset 5 --limit 3# Search for specific topicuv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <path> --search "error"```## Step 4: Drill Into a TurnSee everything about a specific exchange — thinking, tool calls, tool results, costs:```bashuv 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 Workflow1. `--mode toc` → scan the session, find interesting exchanges2. Default (conversation) → read the human-readable flow3. `--mode turn --turn N` → drill into specific exchanges4. `--mode subagents` → review delegated work and follow subagent session paths## Subagent Drill-DownSubagent session files can be read with the same script:```bash# From --mode subagents output, grab the JSONL pathuv run ${CLAUDE_SKILL_ROOT}/scripts/read_session.py <subagent-jsonl-path> --mode toc```## Session Format ReferenceRead `${CLAUDE_SKILL_ROOT}/references/session-format.md` only if custom parsing is needed.

Frequently asked questions