Run node scripts/inspect.mjs list; it resolves storage and returns bounded metadata.
Narrow with a literal name/ID/cwd query, --cwd <exact-session-cwd>, or --since YYYY-MM-DD / --until YYYY-MM-DD (inclusive UTC session start dates).
Page with --offset N --limit N; maximum limit is 100.
Run node scripts/inspect.mjs show <id-prefix|exact-name|discovered-file>; duplicate names or prefixes are errors, so choose an exact ID or discovered file.
Use --view branch for history or --view context for model context; --leaf <entry-id> selects another branch.
Timeline rows include source line and entry ID. --text returns bounded user, assistant, and summary excerpts; --content returns each entry's complete non-structural fields under payload, including tool arguments/results, errors, thinking, images, Bash output, and custom state.
Default leaf is the last persisted entry, not an unrecorded live /tree cursor. Branch counts cover persisted messages; context counts include retained-tail messages separately.
Examples
node scripts/inspect.mjs list "tune"
node scripts/inspect.mjs list --since 2026-09-01 --limit 10
node scripts/inspect.mjs show "tune bugs" --view context --text
node scripts/inspect.mjs show 01a07693 --view branch --content --offset 50 --limit 50
Project-relative paths resolve against cwd. Otherwise try ~/.local/state/pi/sessions, then agent-dir sessions, then cwd .pi/sessions.
Stop at the first store containing JSONL files. An explicitly configured empty or missing directory never falls through.
Never search outside these roots; directory and file symlinks are not followed.
Validation and interpretation
Unfiltered lists validate every discovered session. Date/cwd filters may skip a body only after a valid header proves it is out of scope; invalid headers and in-scope files remain errors, and query/pagination never permit skipping.
complete means every candidate was fully parsed or safely excluded; scanned, parsed, and skipped distinguish outcomes. List exits nonzero when any unresolved file fails validation.
An unfinished live JSONL line is an error; retry after its writer finishes.
Report malformed/unsupported sessions by file and line, never by contents.
Do not count abandoned branches or retained-tail copies as additional user turns.
# Inspector workflow and limits
## Workflow
- Run `node scripts/inspect.mjs list`; it resolves storage and returns bounded metadata.
- Narrow with a literal name/ID/cwd query, `--cwd <exact-session-cwd>`, or `--since YYYY-MM-DD` / `--until YYYY-MM-DD` (inclusive UTC session start dates).
- Page with `--offset N --limit N`; maximum limit is 100.
- Run `node scripts/inspect.mjs show <id-prefix|exact-name|discovered-file>`; duplicate names or prefixes are errors, so choose an exact ID or discovered file.
- Use `--view branch` for history or `--view context` for model context; `--leaf <entry-id>` selects another branch.
- Timeline rows include source line and entry ID. `--text` returns bounded user, assistant, and summary excerpts; `--content` returns each entry's complete non-structural fields under `payload`, including tool arguments/results, errors, thinking, images, Bash output, and custom state.
- Default leaf is the last persisted entry, not an unrecorded live `/tree` cursor. Branch counts cover persisted messages; context counts include retained-tail messages separately.
## Examples
```sh
node scripts/inspect.mjs list "tune"
node scripts/inspect.mjs list --since 2026-09-01 --limit 10
node scripts/inspect.mjs show "tune bugs" --view context --text
node scripts/inspect.mjs show 01a07693 --view branch --content --offset 50 --limit 50
```
## Storage resolution
- Precedence: CLI `--session-dir` → `PI_CODING_AGENT_SESSION_DIR` → project `.pi/settings.json` `sessionDir` → global `${PI_CODING_AGENT_DIR:-~/.pi/agent}/settings.json` `sessionDir`.
- Project-relative paths resolve against cwd. Otherwise try `~/.local/state/pi/sessions`, then agent-dir `sessions`, then cwd `.pi/sessions`.
- Stop at the first store containing JSONL files. An explicitly configured empty or missing directory never falls through.
- Never search outside these roots; directory and file symlinks are not followed.
## Validation and interpretation
- Unfiltered lists validate every discovered session. Date/cwd filters may skip a body only after a valid header proves it is out of scope; invalid headers and in-scope files remain errors, and query/pagination never permit skipping.
- `complete` means every candidate was fully parsed or safely excluded; `scanned`, `parsed`, and `skipped` distinguish outcomes. List exits nonzero when any unresolved file fails validation.
- An unfinished live JSONL line is an error; retry after its writer finishes.
- Report malformed/unsupported sessions by file and line, never by contents.
- Do not count abandoned branches or retained-tail copies as additional user turns.