# Pi Session Jsonl

> Indexes, searches, inspects, and audits raw Pi coding-agent session JSONL files, including branches, compactions, tool-call/result links, failures, file activity, and unanswered turns. Use when summarizing, recovering, debugging, handing off, or locating exact evidence in `~/.pi/agent/sessions/**/*.jsonl` or another Pi session trace.

- Skill: `dwsy/pi-session-jsonl` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dwsy/pi-session-jsonl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dwsy/pi-session-jsonl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Dwsy (https://skillmd.com/u/dwsy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dwsy/pi-session-jsonl

---


# Pi Session JSONL

Treat a session as an evidence tree, not a flat transcript. Use the bundled TypeScript CLI to create a compact index, query narrow evidence, and open exact records only when needed.

## Resolve the script

Use the absolute path to this skill directory from the `read` call that loaded `SKILL.md`:

```bash
node --experimental-strip-types <skill-dir>/scripts/pi-session-index.ts --help
```

Never copy the whole raw JSONL into model context.

## Workflow

1. For a quick active-branch check, run `overview`.
2. For a large, branching, or unfinished session, run `index` with `--scope all`.
3. Use `search` to locate user requests, tool calls, failures, paths, validation markers, compactions, and summaries.
4. Use `show` with an entry ID, JSONL line, or tool-call ID to inspect exact evidence.
5. Read generated Markdown chunks only for the semantic phases needed by the answer.

```bash
SCRIPT=<skill-dir>/scripts/pi-session-index.ts
SESSION=/absolute/path/session.jsonl
INDEX=/tmp/pi-session-index

node --experimental-strip-types "$SCRIPT" overview "$SESSION"
node --experimental-strip-types "$SCRIPT" index "$SESSION" --out-dir "$INDEX" --scope all
node --experimental-strip-types "$SCRIPT" search "$INDEX" --query 'FAIL|BUILD FAILED|errorCode' --regex --limit 30
node --experimental-strip-types "$SCRIPT" search "$INDEX" --tool bash --failed-only --limit 30
node --experimental-strip-types "$SCRIPT" search "$INDEX" --path 'src/auth.ts' --limit 30
node --experimental-strip-types "$SCRIPT" show "$INDEX" --tool-call call_123 --raw
```

`index` writes `overview.json`, `index.jsonl`, `timeline.jsonl`, `manifest.json`, and `chunks/*.md`. The CLI reports when an index is stale relative to its source JSONL.

## Query guidance

- Prefer literal `--query`; add `--regex` only for a real pattern.
- Narrow with `--kind`, `--role`, `--tool`, `--path`, or `--failed-only` before increasing `--limit`.
- Use `--scope active` for the inferred/current path and `--scope all` when abandoned branches matter.
- Use `--leaf <entry-id>` when the intended branch is known. Otherwise, active-leaf selection is explicitly marked as inferred.
- `show --raw` is the source-of-truth check after search results point to decisive lines.

## Evidence rules

- Link `assistant.toolCall.id` to `toolResult.toolCallId`; parentage is not the tool link.
- `toolResult.isError=false` only means the wrapper did not throw. Inspect embedded exit codes, `FAIL`, compile errors, and validation markers.
- Treat compaction and branch summaries as navigation aids until corroborated by mutation and validation evidence.
- Separate deterministic `write`/`edit` evidence from bash mutation candidates.
- Distinguish verified complete, implemented but unverified, attempted, claimed, and unresolved work.
- State when the final user turn has no complete assistant answer or when production/device verification was not performed.

See [references/pi-session-format.md](references/pi-session-format.md) for format and index semantics.