--- name: prose description: ALWAYS CHECK FIRST when you need to orient on recent work or find a specific thing said in a past session. `prose` is a near-stateless CLI that reads agent session journals (Claude Code CLI, ACP, Codex, opencode, Cursor). Five read verbs (`snap`, `whisper`, `grep`, `session`, `stats`) are pure — no LLM; two compaction verbs (`gossip`, `standup`) layer one cheap LLM pass on top; one stateful verb (`baton`) persists "you are here" markers. Don't say "I don't remember" or guess from filenames before running prose. Use `grep` when the user references a specific phrase, term, file, or quote from a past session. Use `session ` to drill into a specific session — the ids printed in snap/whisper headers are direct handles. Use `baton set` to leave a sign-off for the next session and `baton` to read the latest. Also fire when the user mentions prose itself ("look at prose", "show me prose", "does prose work", "try prose") — default to `snap`, never dump `--help` and ask what to do. --- # prose — Stateless Inspection Over Your Agent Journal `prose` is the cheap orientation tool over your AI session history. It reads what your agents (Claude Code CLI, brain personas via ACP, Codex, opencode, Cursor) have already written to disk. The read verbs are pure read-side — every call is current; no cursors, no caches, no coordination overhead. The one exception is `baton`: a deliberately stateful "you are here" marker you write at a sign-off and read back next session (persisted to the `~/.prose` vault, so it syncs across machines). **Reach for prose when:** - The user references "earlier," "yesterday," "what we were doing," or assumes shared context you don't have. - You're starting a session in a known repo and want to know what happened before. - The user asks what they were working on (in this project, the family, or the whole week). - The user references a specific term, phrase, error message, or quote from a past session ("the bit about migrations," "where we discussed X") — that's `grep`, not `snap`/`whisper`, since recency-based verbs only see tails. - A prior verb (`snap`, `whisper`, `grep`) surfaced a session id and you want the *whole* session — that's `session `. The 8-char prefix printed in the `=== Claude Code session 72a5eed3 ===` header is the handle. - You're tempted to say "I don't have context on that" — check prose first; the data is on disk. - You need to feed a recent session into your reasoning without retracing. - The user references the prose tool itself ("look at prose", "show me prose", "does prose work", "try prose") — run `snap`, don't dump `--help` and ask what to do. Demonstrating the tool *is* the answer. **Don't use prose when:** - The data you need is current code state — use `Read` / `Grep`. - The user wants persistent memory or fragments — that's `prose evolve`/`search`, different surface. - You're looking at runtime errors of a running app — use `sidetrack`. - You're orienting on the brain graph state — use `ctx`. ## The verb grid Two axes: **scope** (how wide a net) and **compaction** (verbatim or LLM paragraph). | | verbatim | LLM compaction | |------------------------------|------------------|----------------| | 1 cwd | `snap` | — | | neighborhood (project family)| `whisper` | `gossip` | | all cwds, time-windowed | — | `standup` | | all cwds, regex-targeted | `grep` | — | | all cwds, quantitative | `stats` | — | | 1 session by id | `session` | — | Read verbs (`snap`, `whisper`, `grep`, `session`, `stats`) are pure — no LLM, no API key, instant, free. Compaction verbs (`gossip`, `standup`) layer one streaming LLM pass on top. ## Pick the right verb **`snap`** — Verbatim, single cwd, no LLM, instant. - Use when you want the exact words for *this* repo, the raw transcript, or to feed sessions into your own LLM reasoning. - Cheap: filesystem read, zero token spend. **`whisper`** — Verbatim, neighborhood-aware, no LLM. - Use when you want raw recent activity across the *project family* (e.g. running it in `~/src/6digit-studio` includes the entire `6digit-*` family; `~/src/koru` includes `korulang_org` and other token-related siblings). - Pass `--cwd-only` to scope to a single directory (then it's basically snap with neighborhood-skip). - Cheap: filesystem reads only, zero token spend. Use this as the verbatim source for your own pipelines. **`gossip`** — One short LLM paragraph over a `whisper`. - Use when you want a quick narrative answer to "what's happening across this project family lately." - Casual register — colleague catching you up over coffee. - Cheap: one LLM pass, gemini-flash by default, pennies. **`standup`** — Structured cross-project breakdown of the last 7 days. - Use when you want to know what's been happening across **all** your work, project-by-project, this week. - Time-windowed (default 7d), per-session tail of last 10 messages, grouped by repo, headered output. - Formal register — daily-standup tone, "what changed / what's next." - Cheap: one LLM pass over a byte-budgeted window. **`grep`** — Regex search across the parsed session line-stream, no LLM. - Use when the user references a specific phrase, file, term, error string, or quote from a past session — when recency-based verbs (`snap`/`whisper`) won't surface it because it's outside the recent tail. - Operates on the **parsed session content**, NOT on files on disk. Multiple positional patterns are OR-alternated; output is grep-style line context (default ±5). - Default scope is global: all sources, all cwds, all time. Use `--cwd`, `--source`, `--since` to narrow. - `-F` for literal strings, `-i` for case-insensitive, `-C N` / `-A N` / `-B N` for context windows, `-m N` to cap matches. - Cheap: filesystem read + in-memory regex, zero token spend. **`stats`** — Per-day activity metrics across all sessions, no LLM. - Use when the question is *quantitative*: "how much did I work this week," "how many sessions/projects per day," "what hours am I active." Not for content — no message text in the output. - Per local-calendar-day: active hours (message timestamps merged with a 15m idle-gap cutoff), "human" hours (user messages only — presence, not agent runtime), user/assistant message counts, distinct sessions and projects, plus an hour-of-day histogram. - Default scope is global (all cwds), last 30 days. Use `--cwd`, `--source`, `--since`, `--idle-gap` to narrow or tune. - `--csv` emits day rows for spreadsheets/plotting; `--json` for the full structure. - Cheap: filesystem read + counting, zero token spend. **`session `** — Verbatim readout of one specific session, no LLM. - The drill-down companion to snap/whisper/grep. When those verbs print `=== Claude Code session 72a5eed3 ===`, pass that prefix (or any unique prefix) to `prose session 72a5eed3` to read the whole session. - Accepts any unambiguous id prefix; errors clearly on no-match (exit 1) or ambiguous-match (exit 2 with the candidate list). - No cwd filter — the id is the selector. Scans Claude Code, ACP, Codex, opencode, Cursor, and Gemini Antigravity (the widest id-space of any verb). - Knobs: `--turns N` to tail, `--since ` to slice by timestamp, `--max-message-bytes N` (default 0, no clipping — opposite of snap, since named-session means you want the full text). - Cheap: filesystem read, zero token spend. ## Decision tree (rough) ``` Need raw text for THIS cwd? → prose snap Need raw text across the project family? → prose whisper Need a paragraph about the family? → prose gossip Need "what did I do this week"? → prose standup Need to find a specific phrase/term/quote? → prose grep "..." Need numbers (hours, volumes, cadence)? → prose stats Have an id from snap/whisper/grep? → prose session ``` ## Multi-source by default `snap`, `whisper`, `grep`, and `stats` read the **union** of: - Claude Code CLI sessions in `~/.claude/projects/` - Brain-persona ACP sessions (claude-agent-acp writes the same JSONL format to the same path) - Codex CLI sessions in `~/.codex/sessions/` - opencode (sst/opencode) sessions in `~/.local/share/opencode/opencode.db` (SQLite) - Cursor agent transcripts in `~/.cursor/projects//agent-transcripts/` (JSONL; timestamps synthesized from file mtime, since Cursor records none) `session ` resolves against that same union **plus** Gemini Antigravity brain artifacts in `~/.gemini/antigravity/brain/` — its id-space is the widest of any verb, so a named id always resolves regardless of source. A `gossip` in a directory automatically picks up what your terminal CLI, ACP-driven brain personas, Codex, opencode, and Cursor have all been doing there. The boundary between surfaces mostly disappears at the inspection layer. Sources you don't use are silently no-ops — no config to disable. ## Stateless — call it freely These verbs hold zero state. There's no "last run," no cursor, no cache. Multiple consumers (terminal, satellite tool, REST endpoint, another Claude session) can call them concurrently and always get a current answer. **Don't worry about whether you should "save" a result for later** — just call again next time you need it. ## Batons — the one stateful verb (leave a sign-off, read it back) The read verbs reconstruct the past; a **baton** records *where you are now* for the next session to pick up. It's the deliberate exception to statelessness — a small, typed, persisted "you are here" marker. - **Write one at a sign-off:** `prose baton set "↪ HANDOFF: position — what merged · next: · or pivot"`. The `↪ LABEL:` prefix sets the type; or pass `--type