elliot-stack 1.0.18 → 1.0.20

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,423 @@
+# 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`, `engagement`. 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. Answers "what was I doing, when?". It is a *map* of session activity —
+Claude's work included — and makes no claim about attention time; for "how much
+time did this consume?" use `engagement`. 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, 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,
+span_minutes, sessions}}`.
+
+### `engagement`
+
+Attention-time accounting: how much focused time a window, project, or session
+actually consumed — *your* time, not Claude's. Answers "how long did X actually
+take me?". Defaults to all projects and today; with `--file` and no time flags,
+the window is the session's own first→last prompt.
+
+```bash
+# Today's real work time, everything
+python read_transcript.py --mode engagement --date today
+
+# One project over a week
+python read_transcript.py --mode engagement --project keel --since 7d
+
+# One session, strict 5-minute break threshold
+python read_transcript.py --mode engagement --file <session.jsonl> --break 5m
+```
+
+How it works — three deterministic rules over ONE merged stream:
+
+1. Real user prompts (typed messages and slash commands — not tool results,
+   hook/skill injections, or compact continuations) from EVERY project are
+   merged into a single chronological stream. A gap between consecutive prompts
+   ≤ `--break` (default 10m) counts fully as active time, attributed to the
+   session of the *later* prompt — the chat being read/typed in. One stream
+   means a moment of wall clock is never counted twice across parallel chats.
+2. A longer gap still counts in full if Claude was working in that session
+   during the gap and the user replied within `--break` of Claude's last event
+   (sitting-there-waiting credit). Long runs you walked away from get nothing.
+3. Everything else is a break and contributes zero. A session left open with no
+   prompts accrues nothing.
+
+Output: one row per session (active, ratio = active/elapsed, prompt count,
+first–last), a totals line (already interval-merged — safe to quote), breaks in
+the merged stream, and (single-session view) median/p90 prompt gaps. Ratio is
+capped at 1.0: composing time leading into a chat's first prompt is credited to
+that chat, so raw active can slightly exceed its first–last span.
+
+Scoping caveat: `--project`/`--cwd`/`--file` filter which sessions are
+*reported*; the stream is always computed across all projects under `--root` so
+parallel-chat math stays correct. A scoped total can be less than the global
+total for the same window.
+
+Flags:
+- `--break <spec>` — break threshold: `5m`, `20m`, `1h` (default 10m).
+- `--date` / `--since` / `--until` — window (same semantics as timeline).
+- `--cwd` / `--project` / `--all-projects` / `--file` — reporting scope.
+- `--tz` — display timezone.
+- `--exclude-current` — drop the current session from stream and report.
+
+JSON shape: `{since, until, break_minutes, sessions: [{uuid, project, title,
+path, first, last, elapsed_minutes, active_minutes, active_seconds, ratio,
+user_messages}], totals: {sessions, active_minutes, active_seconds,
+span_minutes}, stream_breaks: [{start, end, minutes}]}`.
+
+---
+
+## 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 |
+| `engagement` | see the `engagement` 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)