elliot-stack 1.0.17 → 1.0.19

package/skills/estack-read-claude-session-history/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: estack-read-claude-session-history
+description: (read-claude-session-history) Invoke for ANY task involving Claude Code session history, transcripts, or .jsonl files — this is the only way to read, parse, or search them; do not attempt to use Bash or Read on .jsonl directly. Use for: recovering context after /compact ("what were we doing before compact"), advisor response retrieval ("what did the advisor say"), subagent output collection ("get all subagent finals"), cross-project session search by keyword, session listing and triage, UUID and title lookup, resume-command generation, file-edit and tool-call forensics, session diff between two sessions or subagents, weekly work journal, day timeline of activity blocks and idle gaps, recovering from .claude-backups after data loss, session count queries, and reading the last agent message before a crash or interrupt. Trigger phrases: "session history", "before compact", "what did claude do", "what did I work on", "search my sessions", "find that session", "what did the advisor say", "what did the agent edit", "from the backup", "list my sessions", "subagent outputs", "session journal", "resume previous", "which files did claude touch", "go back and look", "what did I do yesterday", "where did my day go", "timeline of my day", "how much time on".
+---
+
+# Read Claude Session History
+
+Search, read, recover, and compare Claude Code session history — across the current session, prior sessions, sibling subagents, all projects, and `.claude-backups` snapshots.
+
+Sessions are stored as `.jsonl` files. Reading them raw is hopeless: 1,000–5,000+ lines of dense JSON per session, 33+ project directories, hundreds of historical sessions. This skill wraps a single CLI that knows the entry schema and exposes ~20 modes.
+
+## Quick start
+
+```bash
+PY="C:\Users\2supe\.claude\skills\read-claude-session-history\scripts\read_transcript.py"
+
+# What was the last thing the agent said in this session?
+python "$PY" --file <current-session.jsonl> --mode last
+
+# Get a 6-line summary of any session (intent, last activity, edits, tool counts, subagent fanout)
+python "$PY" --file <session.jsonl> --mode brief
+
+# Recover what got cut off by the most recent /compact
+python "$PY" --file <session.jsonl> --mode pre-compact
+
+# Find a session by UUID prefix across all projects
+python "$PY" --mode lookup --uuid abc123de
+
+# Search every session in every project for a phrase
+python "$PY" --mode search --all-projects --query "supabase migration"
+
+# Pull subagent outputs from a fan-out investigation
+python "$PY" --file <parent.jsonl> --mode subagent-finals
+
+# Block-grouped timeline of a whole day across all sessions, with idle gaps
+python "$PY" --mode timeline --date yesterday
+
+# Any mode as structured JSON for piping into the next step
+python "$PY" --mode list --project keel --since 7d --format json
+```
+
+## Time handling — READ THIS before doing anything with time
+
+**Every time the CLI displays is already the user's local time.** JSONL files store
+UTC; the script converts on output. Do NOT add or subtract timezone offsets
+yourself, do NOT cross-reference file mtimes to infer the timezone, and do NOT
+treat raw `"timestamp"` fields from a .jsonl (which ARE UTC) as comparable to CLI
+output. If you need a different zone, pass `--tz` (IANA name like
+`America/New_York`, `UTC`, or an offset like `-4`) — never convert manually.
+`--since/--until/--date` specs are interpreted in that same display timezone.
+
+## Decision tree
+
+```
+What are you trying to do?
+│
+├─ Read the current session / one specific session
+│  ├─ Last assistant message ──────────────────── --mode last
+│  ├─ All advisor responses ───────────────────── --mode advisor
+│  ├─ Content cut off by /compact ─────────────── --mode pre-compact
+│  ├─ Full human-readable dump ────────────────── --mode dump (size-aware)
+│  ├─ 6-line summary for triage ───────────────── --mode brief
+│  └─ Schema/structural diagnosis ─────────────── --mode debug
+│
+├─ Find a session I don't have the path for
+│  ├─ By UUID prefix ──────────────────────────── --mode lookup --uuid <prefix>
+│  ├─ By title or first prompt ────────────────── --mode find --title|--first-prompt
+│  └─ Generate a `claude --resume` command ───── --mode resume-cmd --uuid <prefix>
+│
+├─ Search content
+│  ├─ One session ─────────────────────────────── --mode search --file …
+│  ├─ One project ─────────────────────────────── --mode search --cwd …
+│  ├─ All projects ────────────────────────────── --mode search --all-projects
+│  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
+│
+├─ Forensics on a session
+│  ├─ Chronological tool-call log ────────────── --mode changelog
+│  ├─ Every file touched ─────────────────────── --mode file-edits
+│  └─ Every tool call (optionally filtered) ──── --mode tool-calls --tool Bash,Edit
+│
+├─ Subagent (fan-out) work
+│  ├─ List spawned subagents ─────────────────── --mode subagent-list
+│  ├─ Get every subagent's final message ─────── --mode subagent-finals
+│  └─ Forensics on one subagent ──────────────── --mode subagent-tools|subagent-files --subagent …
+│
+├─ Cross-cutting reporting
+│  ├─ "What did I do this week?" ──────────────── --mode journal --since 7d
+│  ├─ "Where did my day go?" / day timeline ───── --mode timeline --date yesterday
+│  ├─ "How much time on <project>?" ───────────── --mode timeline --project <name> --date …
+│  ├─ Count sessions matching a query ─────────── --mode count --query …
+│  └─ Resume where I left off in this project ─── --mode resume-prev --cwd …
+│
+└─ Compare two sessions or two sibling subagents
+   └─ Interleaved diff ──────────────────────── --mode diff --file-a … --file-b …  (or --subagents-of …)
+```
+
+## Quick reference
+
+| Mode | Required flags | Returns |
+|---|---|---|
+| `last` | `--file` | Last N assistant text outputs |
+| `advisor` | `--file` | All `advisor_tool_result` payloads |
+| `pre-compact` | `--file` | 40 exchanges before the most recent `/compact` |
+| `dump` | `--file` | Human-readable dump (auto-degrades on transcripts >5MB) |
+| `search` | `--query` + scope | Matches windowed for context (supports `--role`, `--in text|tool_use|thinking|all`) |
+| `debug` | `--file` | Entry/block type distributions + probes |
+| `brief` | `--file` | 6-line summary: uuid·project·mtime·status / intent / last / edits / tools / subagents |
+| `list` | `--cwd` or `--all-projects` | Rich table: mtime, size, uuid, msg count, flags, status, title |
+| `lookup` | `--uuid <prefix>` | Absolute path (exit 1 missing, exit 2 ambiguous) |
+| `find` | `--title` or `--first-prompt` | Sessions ranked by recency |
+| `resume-cmd` | `--uuid <prefix>` | `cd <cwd>; claude --resume <uuid>` snippet |
+| `changelog` | `--file` | `HH:MM:SS  TOOL  one-line-summary`, day-grouped |
+| `file-edits` | `--file` | Unique paths sorted with op tags |
+| `tool-calls` | `--file` (+ `--tool` filter) | Timestamped per-call blocks |
+| `subagent-list` | `--file` | List sibling subagents with agentType + description |
+| `subagent-finals` | `--file` | Every subagent's final assistant message |
+| `subagent-tools` | `--subagent` | Forensics on one subagent |
+| `subagent-files` | `--subagent` | Files one subagent touched |
+| `resume-prev` | `--cwd` | Banner + dump-style tail of last 10 exchanges |
+| `count` | `--query` (+ scope) | `<N>` to stdout, summary to stderr |
+| `journal` | `--since` (+ scope) | Per-session 5-line block: date·uuid / prompt / ended / edits / tools |
+| `timeline` | `--date` or `--since/--until` (defaults: today, all projects) | Block-grouped day timeline across sessions with idle gaps + active-time totals |
+| `diff` | `--file-a` + `--file-b` OR `--subagents-of` | Timestamp-interleaved A>/B> output |
+
+## Global flags
+
+- `--root {live|mirror|snapshot-24h|snapshot-1w|snapshot-1mo|<abs-path>}` — read from a `.claude-backups` mirror or snapshot instead of live. Default `live`.
+- `--cwd <path>` — single-project scope. Use the original working directory (e.g. `"C:\Users\2supe\Other Claude Code"`).
+- `--all-projects` — walk every project under `--root`.
+- `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`. Use this instead of `--cwd` when you know the project's name but not its exact path.
+- `--file <path>` — single-session scope.
+- `--since <spec>` / `--until <spec>` — accepts ISO date, ISO datetime, relative (`30m`, `24h`, `7d`, `1w`, `1mo`), named (`today`, `yesterday`, `now`).
+- `--date <spec>` — single-day window for `timeline` (`--date yesterday`, `--date 2026-06-01`).
+- `--gap <spec>` — idle-gap threshold for `timeline` blocks (`15m` default, `1h`).
+- `--tz <spec>` — display timezone override (IANA name, `UTC`, or offset like `-4`). Default: system local time.
+- `--format json` (or `--json`) — structured JSON output on every mode (except the legacy `--list`/`--list-subagents` aliases). Pipe-friendly: paths are strings, timestamps ISO.
+- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, and `timeline`.
+- `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`.
+- `--force-dump` — bypass the 5 MB `dump` guard.
+- `-n N` — count modifier (default 5 for `last`, 80 for `dump`, 10 for `resume-prev`).
+
+The current session is marked with `[*]` in `list` output. Status glyphs: ✓ clean, ! interrupted, ? pending-user, ● active. Sessions with a compact marker get `[C]`; sessions with subagents get `[S]`.
+
+## Backup-aware reads
+
+In March 2026 a Claude Code auto-update deleted live `.jsonl` transcripts (GitHub #41591). To survive that class of incident, this machine maintains four backup roots under `C:\Users\2supe\.claude-backups\`:
+
+- `mirror` — continuous mirror
+- `snapshot-24h` — 24-hour-old snapshot
+- `snapshot-1w` — 1-week-old snapshot
+- `snapshot-1mo` — 1-month-old snapshot
+
+Any mode accepts `--root <name>`. The resolved root is printed to stderr.
+
+```bash
+# Find a session that was deleted from live but still in yesterday's snapshot
+python "$PY" --root snapshot-24h --mode lookup --uuid <prefix>
+
+# Compare today's mirror against a week ago to confirm what was lost
+python "$PY" --root snapshot-1w --cwd "C:\Users\2supe\Other Claude Code" --list
+```
+
+See `references/recipes.md` → "Deletion-incident recovery" for the full playbook.
+
+## Common workflows
+
+| Need | Command |
+|---|---|
+| Recover advisor output that scrolled out of context | `--file <session> --mode advisor` |
+| Get back to what you were doing before `/compact` | `--file <session> --mode pre-compact` |
+| Fan-out triage: 14 subagents, want all of their finals | `--file <parent> --mode subagent-finals` (or `--mode brief --include-subagents`) |
+| Find "that session where I asked about supabase rate limits" | `--mode search --all-projects --query "supabase rate limits"` |
+| Resume a project after a few days away | `--mode resume-prev --cwd "<project path>"` |
+| Daily/weekly journal | `--mode journal --since 7d --all-projects` |
+| "Where did yesterday go?" | `--mode timeline --date yesterday` |
+| "How much time on Keel today?" | `--mode timeline --project keel --date today` |
+| Feed session data into a script | any mode + `--format json` |
+
+See `references/recipes.md` for fuller multi-step workflows.
+
+## Windows notes
+
+- Use `python` (not `python3`) on this Windows setup.
+- The script handles UTF-8 stdout/stderr internally — both PowerShell and Bash work fine for single commands.
+- **Piping `--format json` into another command: use Bash.** PowerShell 5.1 pipes inject a UTF-8 BOM and re-encode through the console codepage, breaking `json.load` (see `references/recipes.md` §5c for the PowerShell workaround).
+- File paths with spaces need quoting: `--cwd "C:\Users\2supe\Other Claude Code"`.
+
+## Reference docs
+
+- `references/modes.md` — complete per-mode reference (every flag, every example, exit codes).
+- `references/jsonl-schema.md` — entry/block schema, subagent meta sidecars, compact-marker shape.
+- `references/recipes.md` — multi-step workflows (post-compact recovery, find-then-dump, deletion recovery, week-in-review journal, sibling-agent diff).
+
+## When the modes return empty
+
+If a mode returns empty/unexpected output, run `--mode debug` first. It prints the entry-type distribution, content-block types, and probes for advisor + compact markers — useful when the transcript schema has drifted or when a session was truncated.

package/skills/estack-read-claude-session-history/references/jsonl-schema.md

@@ -0,0 +1,126 @@
+# JSONL schema reference
+
+What's actually inside a Claude Code session `.jsonl`. Only relevant when extending the script or debugging an unexpected empty result.
+
+## File location
+
+```
+C:\Users\<user>\.claude\projects\<encoded-cwd>\<session-uuid>.jsonl
+```
+
+The `<encoded-cwd>` is the original working directory with every `:`, `\`, `/`, and whitespace character replaced by `-`. Examples on this machine:
+
+| Original CWD | Encoded directory |
+|---|---|
+| `C:\Users\2supe\Other Claude Code` | `C--Users-2supe-Other-Claude-Code` |
+| `C:\Users\2supe\Other Claude Code\Personal Brand Project` | `C--Users-2supe-Other-Claude-Code-Personal-Brand-Project` |
+| `C:\Users\2supe\AppData\Local\Temp` | `C--Users-2supe-AppData-Local-Temp` |
+
+The encoding is lossy — single hyphens in the original path collapse into the same hyphens that separate segments. Use `--mode lookup` / `--mode find` to recover the actual session path; `decode_project_name()` produces a display-only approximation.
+
+## Backup roots
+
+The same encoded-directory layout exists under each `.claude-backups\<name>\projects\` root:
+
+```
+C:\Users\2supe\.claude-backups\
+  ├── mirror\projects\<encoded-cwd>\<uuid>.jsonl
+  ├── snapshot-24h\projects\<encoded-cwd>\<uuid>.jsonl
+  ├── snapshot-1w\projects\<encoded-cwd>\<uuid>.jsonl
+  └── snapshot-1mo\projects\<encoded-cwd>\<uuid>.jsonl
+```
+
+`--root mirror|snapshot-24h|snapshot-1w|snapshot-1mo` rebases all path resolution to that snapshot. An absolute path argument is also accepted.
+
+## Subagent transcripts
+
+When a session spawns subagents (via the `Agent` / `Task` tool), each subagent's own transcript is written to:
+
+```
+<project-dir>\<session-uuid>\subagents\agent-<id>.jsonl
+```
+
+A sidecar metadata file lives next to it:
+
+```
+<project-dir>\<session-uuid>\subagents\agent-<id>.meta.json
+```
+
+The meta file contains:
+
+```json
+{
+  "agentType": "Explore",
+  "description": "Find every reference to X"
+}
+```
+
+When the meta file is missing, `subagents.load_meta` returns `{"agentType": "unknown", "description": ""}`.
+
+Subagent entries inside the parent transcript are marked with `isSidechain: true` and carry an `agentId` field.
+
+## Entry types
+
+Each line in a `.jsonl` is a JSON object with a `type` field. Entry classifications:
+
+| `type` value | Classification | Notes |
+|---|---|---|
+| `user` | signal (user) | `message.content` may be string or array. Compact markers live here. |
+| `assistant` | signal (assistant) | `message.content` is always an array of blocks. |
+| `ai-title` / `custom-title` | title | `aiTitle` / `customTitle` field carries the session title. |
+| `permission-mode` | noise | mode change events |
+| `attachment` | noise | file attachments |
+| `last-prompt` | noise | cached last prompt |
+| `queue-operation` | noise | internal queueing |
+| `file-history-snapshot` | noise | file state snapshots |
+| `system` | noise | system events |
+| `agent-name` | noise | agent name metadata |
+| `pr-link` | noise | PR linkage |
+
+The `noise` and `title` entries are skipped by `get_messages()`. `debug` mode prints the full distribution.
+
+## Assistant content block types
+
+The `message.content` array for assistant entries can hold:
+
+| Block `type` | Field of interest | Meaning |
+|---|---|---|
+| `text` | `text` | The actual assistant text output. |
+| `thinking` | `thinking` (or `text`) | Model internal reasoning. |
+| `tool_use` | `name`, `input`, `id` | A regular tool call. `id` is the matching id for any later `tool_result`. |
+| `server_tool_use` | `name`, `input` | Server-side tool call (e.g., advisor invocation). |
+| `advisor_tool_result` | `content.text` | The advisor's reply. Always nested as `block.content.text`. |
+| `tool_result` | `tool_use_id`, `content` | Result for a prior `tool_use`. `content` is a string or an array of `{type:"text", text:"..."}`. |
+
+## Compact marker
+
+A `/compact` event appears as a `type:"user"` entry whose first text content starts with:
+
+> `"This session is being continued from a previous conversation"`
+
+`classify_entry` returns `"compact"` for these. Everything before the most-recent compact marker is the pre-compact conversation.
+
+## Timestamps
+
+Most entries carry a `timestamp` field in ISO-8601 form (`2026-05-01T10:00:05Z`). `_parse_timestamp` accepts ISO strings, naive ISO, and numeric epoch values. Timezone-aware values are stripped for comparison with `--since`/`--until` (which use local naive datetimes).
+
+## Title entries
+
+Both `ai-title` and `custom-title` entries surface a `aiTitle` / `customTitle` string. `session_summary()` prefers `aiTitle` when both are present.
+
+## Truncation behavior
+
+`iter_lines` drops the final line if it lacks a trailing newline AND fails to parse as JSON, printing `[note: dropped truncated trailing line in <name>]` to stderr. Malformed mid-file lines are dropped silently.
+
+## Status inference
+
+`infer_status(lines, mtime, current_session_id, session_uuid)` returns one of:
+
+| Status | Glyph | Heuristic |
+|---|---|---|
+| `active` | ● | `current_session_id == session_uuid` AND `mtime` within 5 minutes |
+| `interrupted` | ! | Any `tool_use` block lacks a paired `tool_result` |
+| `pending-user` | ? | Last assistant text message ends with `?` |
+| `clean` | ✓ | none of the above |
+
+This is heuristic — it's correct for the majority of real sessions on this machine but can be fooled by, e.g., an assistant message that legitimately ends with a question.

package/skills/estack-read-claude-session-history/references/modes.md

@@ -0,0 +1,366 @@
+# Mode reference
+
+Every mode of `read_transcript.py`, with all flags, exit codes, and worked examples.
+
+For the high-level decision tree, see `../SKILL.md`. For the JSONL schema, see `jsonl-schema.md`. For multi-step workflows, see `recipes.md`.
+
+## CLI grammar
+
+```
+python read_transcript.py [--root <root>] [--cwd <path> | --all-projects | --project <name> | --file <path>]
+                          [--since <spec>] [--until <spec>] [--tz <spec>]
+                          --mode <mode> [mode-specific flags]
+                          [--format json] [--exclude-current] [--include-subagents] [-n N]
+                          [--force-dump]
+```
+
+Global flag notes:
+- `--project <name>` — case-insensitive substring filter on project directory names (encoded or decoded form). Applies to `list`, `journal`, `search`, `count`, `find`, `timeline`. Exit 1 when nothing matches.
+- `--tz <spec>` — display timezone: IANA name (`America/New_York`), `UTC`, or fixed offset (`+5`, `-4`, `+05:30`, `UTC-4`). Default is system local time. All displayed timestamps AND `--since/--until/--date` interpretation use this zone.
+- `--format json` (alias `--json`) — structured output on every mode except the legacy `--list`/`--list-subagents` aliases. Shapes per mode are listed below.
+
+Legacy flags are preserved unchanged:
+- `--list` (alias for `--mode list` with the v1 column layout)
+- `--list-subagents` (alias for `--mode subagent-list` with the v1 column layout)
+
+---
+
+## Single-session modes
+
+### `last`
+
+Last N assistant text outputs.
+
+```bash
+python read_transcript.py --file <path> --mode last [-n 5]
+```
+
+- Default N = 5.
+- With `--include-subagents`, appends each subagent's final assistant message tagged `[subagent <id-short> · <agentType>]`.
+
+### `advisor`
+
+All advisor responses (the contents of every `advisor_tool_result` block).
+
+```bash
+python read_transcript.py --file <path> --mode advisor
+```
+
+### `pre-compact`
+
+40 message-exchanges before the most recent `/compact`.
+
+```bash
+python read_transcript.py --file <path> --mode pre-compact
+```
+
+If no `/compact` marker is present, falls back to `mode_last(10)` with a note.
+
+### `dump`
+
+Human-readable conversation dump (text only, last 80 messages by default).
+
+```bash
+python read_transcript.py --file <path> --mode dump [--include-subagents] [--force-dump]
+```
+
+**Size-aware fallback:** transcripts larger than 5 MB auto-degrade to `pre-compact` (or `last` if no compact marker), with a stderr note. Override with `--force-dump`.
+
+### `debug`
+
+Structural diagnostic — prints entry type distribution, content block types, advisor probe, compact-marker probe, and sample signal entries. Use this first when a mode returns empty/unexpected results.
+
+```bash
+python read_transcript.py --file <path> --mode debug
+```
+
+### `brief`
+
+6-line single-session summary. Designed for fan-out triage: 14 parallel `brief` calls reproduce a 14-subagent investigation deterministically.
+
+```bash
+python read_transcript.py --file <path> --mode brief [--include-subagents]
+```
+
+Output format:
+```
+<uuid> · <decoded-project> · <mtime> · <status> [*]<if current>
+intent:    <first user prompt, 200ch>
+last:      <last assistant text, 200ch>
+edits:     <N> files — <top-3 paths>
+tools:     Bash=X Edit=Y Read=Z …
+subagents: <N> spawned [<agentType counts>]
+```
+
+With `--include-subagents`, appends each subagent's final assistant message.
+
+### `changelog`
+
+`HH:MM:SS  TOOL  one-line-summary`, day-grouped.
+
+```bash
+python read_transcript.py --file <path> --mode changelog
+```
+
+### `file-edits`
+
+Unique file paths touched, sorted alphabetically. Multiple operations on the same file get a count suffix.
+
+```bash
+python read_transcript.py --file <path> --mode file-edits
+```
+
+### `tool-calls`
+
+Timestamped per-call blocks, with formatted args.
+
+```bash
+python read_transcript.py --file <path> --mode tool-calls [--tool Bash,Edit]
+```
+
+`--tool` filters to a comma-separated subset.
+
+---
+
+## Discovery modes
+
+### `list`
+
+Enriched session table.
+
+```bash
+# Single project
+python read_transcript.py --cwd <path> --mode list [--since 7d] [--exclude-current]
+
+# All projects
+python read_transcript.py --all-projects --mode list [--since today]
+```
+
+Columns: marker (`[*]` if current), mtime, size, uuid-short, msg count, flags (`[C]`=compact, `[S]`=subagents), status (✓!?●), decoded project name (when multi-project), title.
+
+For byte-identical v1 output, use the legacy `--list` flag.
+
+### `lookup`
+
+Resolve a UUID prefix to an absolute path.
+
+```bash
+python read_transcript.py --mode lookup --uuid <prefix>
+```
+
+- Exit 0: prints absolute path.
+- Exit 1: no match.
+- Exit 2: ambiguous prefix — prints all matches.
+
+### `find`
+
+Search session metadata by title or first prompt.
+
+```bash
+python read_transcript.py --mode find --title "supabase"
+python read_transcript.py --mode find --first-prompt "fix the bug"
+```
+
+### `resume-cmd`
+
+Generate a `cd <cwd>; claude --resume <uuid>` snippet for a UUID prefix.
+
+```bash
+python read_transcript.py --mode resume-cmd --uuid <prefix>
+```
+
+The original CWD cannot be unambiguously recovered from the encoded directory name; the snippet includes a `<original cwd>` placeholder plus the decoded display name as a hint.
+
+---
+
+## Search modes
+
+### `search`
+
+Cross-scope search with role + channel filters.
+
+```bash
+# Single file
+python read_transcript.py --file <path> --mode search --query "<q>"
+
+# Whole project
+python read_transcript.py --cwd <path> --mode search --query "<q>"
+
+# All projects
+python read_transcript.py --all-projects --mode search --query "<q>"
+```
+
+Flags:
+- `--role {user,assistant,both}` (default `both`)
+- `--in {text,tool_use,thinking,all}` (default `text`)
+- `--since` / `--until`
+
+`--in tool_use` searches the `name + JSON-stringified input` of every `tool_use` block — useful for finding "the session where I ran `git push --force`".
+
+`--in thinking` searches `thinking` blocks (model reasoning).
+
+### `count`
+
+Count sessions matching a query.
+
+```bash
+python read_transcript.py --mode count --query "<q>" [--all-projects] [--since 30d]
+```
+
+stdout: integer session count.
+stderr: `<N> sessions, <M> total messages, <K> matches`.
+
+---
+
+## Subagent modes
+
+### `subagent-list`
+
+List sibling subagents for a parent session.
+
+```bash
+python read_transcript.py --file <parent> --mode subagent-list
+```
+
+Output: `mtime  size  agent-id  type=<agentType>  "<description>"`. The legacy `--list-subagents` flag preserves v1's simpler columns.
+
+### `subagent-finals`
+
+Every subagent's final assistant message, separated by `=== agent-<id> (<type>) ===` headers.
+
+```bash
+python read_transcript.py --file <parent> --mode subagent-finals
+```
+
+### `subagent-tools`
+
+Tool-call forensics on a single subagent (same output shape as `tool-calls`).
+
+```bash
+python read_transcript.py --mode subagent-tools --subagent <subagent-path>
+```
+
+### `subagent-files`
+
+Files touched by a single subagent (same output shape as `file-edits`).
+
+```bash
+python read_transcript.py --mode subagent-files --subagent <subagent-path>
+```
+
+---
+
+## Resume modes
+
+### `resume-prev`
+
+Banner + dump-style tail of the last 10 exchanges from the most-recent prior session in a project.
+
+```bash
+python read_transcript.py --cwd <path> --mode resume-prev [-n 10]
+```
+
+---
+
+## Aggregation modes
+
+### `journal`
+
+Per-session 5-line block: date·uuid·project / prompt / ended / edits / tools.
+
+```bash
+python read_transcript.py --mode journal --since 7d [--cwd <path> | --all-projects | --project <name>]
+```
+
+JSON shape: array of session-summary objects (same fields as `list`).
+
+### `timeline`
+
+Block-grouped activity timeline across all sessions in a time window, with idle
+gaps and active-time totals. Answers "where did my day go?" and "how much time on
+X?". Defaults to all projects and today.
+
+```bash
+# Yesterday, everything
+python read_transcript.py --mode timeline --date yesterday
+
+# One project, today, stricter idle threshold
+python read_transcript.py --mode timeline --project keel --date today --gap 5m
+
+# Arbitrary window
+python read_transcript.py --mode timeline --since 2026-06-01 --until 2026-06-03
+```
+
+How it works: every signal-message timestamp in the window is an activity event;
+events across all sessions are merged chronologically and grouped into blocks
+separated by gaps longer than `--gap` (default 15m). Each block lists the sessions
+active in it with message counts; idle gaps are printed between blocks; a totals
+line gives block count, summed active time, span, and session count.
+
+Flags:
+- `--date <spec>` — single-day window (midnight to midnight). Wins over `--since/--until`.
+- `--since/--until` — arbitrary window (until defaults to now).
+- `--gap <spec>` — idle threshold: `15m`, `20`, `1h`.
+- `--cwd` / `--project` / `--all-projects` — scope (default: all projects).
+- `--tz` — display timezone (timestamps render in it; the window is interpreted in it).
+
+JSON shape: `{since, until, gap_minutes, blocks: [{start, end, duration_minutes,
+sessions: [{uuid, project, title, path, events}]}], totals: {blocks,
+active_minutes, sessions}}`.
+
+---
+
+## Comparison modes
+
+### `diff`
+
+Timestamp-interleaved comparison of two sessions.
+
+```bash
+python read_transcript.py --mode diff --file-a <s1> --file-b <s2>
+```
+
+For sibling-subagent comparison (when a fan-out spawned multiple agents with similar tasks):
+
+```bash
+python read_transcript.py --mode diff --subagents-of <parent>
+```
+
+Output is prefixed `A>` / `B>` (or with subagent id shorts).
+
+---
+
+## JSON shapes per mode (`--format json`)
+
+| Mode | Shape |
+|---|---|
+| `last` | `[{n_from_end, timestamp, text}]` |
+| `advisor` | `[<advisor text>, …]` |
+| `pre-compact` | `{found_compact, messages: [{role, timestamp, is_compact, text}]}` |
+| `dump` | `[{role, timestamp, is_compact, text}]` |
+| `debug` | `{entry_types, block_types, advisor_blocks, compact_markers}` |
+| `brief` | session-summary object (+ `subagent_finals` with `--include-subagents`) |
+| `list` / `journal` / `find` | array of session-summary objects |
+| `lookup` | `{prefix, path, matches}` (same exit codes as text) |
+| `resume-cmd` | `{uuid, path, project, encoded, command}` |
+| `changelog` | `[{timestamp, tool, summary}]` |
+| `tool-calls` / `subagent-tools` | `[{timestamp, tool, summary, input}]` |
+| `file-edits` / `subagent-files` | `[{path, ops}]` |
+| `search` | `[{session, mtime_iso, role, where, timestamp, window}]` |
+| `count` | `{sessions, messages, matches}` |
+| `subagent-list` | `[{id, agentType, description, path, size_kb, mtime_iso}]` |
+| `subagent-finals` | `[{id, agentType, text}]` |
+| `resume-prev` | `{session, path, mtime_iso, messages}` |
+| `diff` | `{a, b, messages: [{source, role, timestamp, text}]}` |
+| `timeline` | see the `timeline` section above |
+
+Session-summary object fields: `path, uuid, mtime, mtime_iso, size, exists, title,
+first_prompt, last_assistant, last_activity, msg_count, edit_count, tool_counts,
+files_touched, subagent_count, subagent_types, has_compact, has_subagents, cwd,
+decoded_project, status, is_current`.
+
+## Exit codes
+
+- `0`: success
+- `1`: missing required flag, no match (including `--project` with zero matches), or file not found
+- `2`: ambiguous result (e.g. UUID prefix matches multiple sessions)