Csift

csift — ripgrep for Claude Code session transcripts

Surface: v0.10.0 (must == csift --version). MECHANICAL GUARD: at first use after any compaction or context restore, run csift --version — if it differs from this Surface line, the copy you are reading is a stale in-context echo, and the installed SKILL.md is the one that matches the binary: Read it before anything else. Same diagnosis when an invocation you were CONFIDENT about errors (an older surface from prefill/summary/habit); never fall back to hand-parsing the jsonl.

Rust CLI over CC session .jsonl under ~/.claude/projects/<encoded-cwd>/. Built for an LLM consumer: token-lean text, uniform JSON, pure regex (RE2-class, linear-time; no backrefs/lookaround — they fail to compile by design). Smart-case: a pattern is case-insensitive unless it carries an uppercase; -i forces insensitive. csift <cmd> --help is the authoritative flag manual. Flag order is genuinely free — before/after the subcommand, before/after positionals, all equivalent.

Why not hand-roll this format

Every row below is measured, not hypothetical, and none of them threw an exception: a hand-written pass returns a plausible number that is wrong in a direction you cannot see.

search "" TARGET --count-by label prints the carrier distribution before you write a line of parsing. The engineer in the 2026-08-28 incident put it best afterwards: "it would also have told me the carrier distribution before I wrote a single line of parsing. I never asked."

Hand-rolling a genuinely special case is fine, and csift is read-only so it will not stop you. What this section exists to prevent is hand-rolling as the DEFAULT, where every trap above fails quietly and the number you report is wrong in a direction you cannot see.

Route by QUESTION — one question ⇒ one command

Two commands read transcript content — pick by intent: show fetches from the live transcript (this includes the tail-peek show T --turn -3..); verbatim reconstructs what a compaction summary already discarded (budget-bounded, crosses boundaries). Everything you want to READ is show; verbatim is only for compaction-clipped history — and it tells you (stderr note) when you use it on a session with no compaction.

Wrong assumptions that cost real sessions

Five laws (all commands)

1. Exit law: an ADDRESS that misses = hard error, exit≠0 (show --line 99, show --turn 99, --uuid, a pinned @id, --agent, recover --file, image --id). A FILTER that matches nothing = honest empty, exit 0 (search, time windows, open/from-end ranges) — and a zero-match search self-diagnoses on stderr: definitive absence + active filters + (under -t/-T) the labels the pattern DOES occur under. Never re-derive syntax because a result came back empty. ONE exit-code exception, wait's timeout = 124 (the GNU timeout convention): a monitor's timeout is a normal outcome a script must branch on; it never extends to any other command or outcome.
2. One range grammar, two axes: every range flag (--line / --turn / --file-lines) takes N · A..B · N.. · ..N · -k (k-th from the END; -3.. = last 3) · .. (all), inclusive. A-B hard-errors with the correct spelling; a statically reversed 9..3 errors at parse. Axes: turn/tN = 0-based logical turn; line/Lnnnn = 1-based physical jsonl line; --file-lines (recover) = the reconstructed FILE's lines. On show, an explicit --turn N/A..B is an address (law 1); open/from-end forms clamp. --turn (windowing) ∧ --since/--until intersect (AND) everywhere.
3. Span law: subagents included by default; --no-subagents restricts; both switches exist everywhere (contradictory pair = parse error). verbatim is the one opt-IN (--subagents; its budget multiplies per session) and the one command that REQUIRES a target. agents rejects both (it LISTS subagents).
4. Caps law — no silent truncation: every cap reports its drop and how to get more. Defaults: list 50 rows on an unscoped all-projects run; show 200 record units (the drop prints the exact continuation command); search/stats uncapped until --max-count N. --max-count 0 = uncapped, uniformly. Malformed lines are counted (N malformed line(s) skipped), never hidden — including obviously-corrupt lines the byte prefilters never parse (free-text garbage, crash-truncation: any non-blank line that isn't {…}-framed); the one undetectable residue is a {…}-framed line whose INTERIOR is invalid JSON on a non-candidate line (validating those would repeal the perf contract). SCOPE of the count: the full-scan commands (search/stats/show/files/recover/verbatim/image) census the whole file; the head/tail readers (list rows, agents rows) census the LINES THEY READ — booked exactly once (the two windows are disjoint), scope-qualified in the text note, and never a whole-file verdict (that is stats). A sidecar marker line the current schema cannot read (schema skew — e.g. a pre-release fossil) counts as malformed too; it never merges and never vanishes.
5. Time law: every TEXT timestamp is local — YYYY-MM-DD HH:MM:SS[.mmm] <TZAB>(UTC±offset), e.g. 2026-07-11 15:33:37 AEST(UTC+10), IST(UTC+05:30). The marker is a format, not a value: name + offset derive from the machine zone at that instant (DST-correct), so the only mental step is "shift by the given offset". No UTC copies in text. Machine time = JSON, always paired: ts_utc+ts_local for a record's own instant, <name>_utc+<name>_local for named instants (first_*, trigger_*, …). Raw bytes = --raw.

Targeting (positional, every command; whoami optional)

@<uuid> one session · @<uuid-prefix> (4-11 hex, unique else error) · @main calling top-level (env) · @trap:<marker> calling SUBAGENT (§trap) · @<agent-id> a subagent + its subtree (ids from agents; bare hex ≥12 or teammate form aVSRepro-68a2… — a teammate name may itself carry dashes, aP1-engine-9cf2…) · ./real path/encoded dir (-Users-…; Windows C--Users-…; UNC via @--server-…) ⇒ project(s) · *.jsonl one transcript · 0 targets ⇒ ALL projects (list caps the unscoped flood; verbatim REQUIRES a target).

• A bare id without @ errors with "did you mean '@…'?" — ids always take @.
• An unrecognized @-shape (a 1-3-char prefix, a dashed fragment, a non-id token) errors naming the grammar — it never falls through to path resolution.
• --sessions-from <FILE|-> (every multi-target command): scope to an id list — whitespace-separated uuid/prefix/agent-id tokens, bare or @-prefixed (exactly what search -l emits); UNION with positionals, per-id fail-loud, an explicitly empty list = empty scope (exit 0 — a pipeline that found nothing propagates nothing).
• search is the one command whose FIRST positional is PATTERN; targets follow: csift search P @<uuid>. A pattern starting @ errors (escape \@); a uuid-shaped pattern prints a stderr note.
• show targets exactly ONE transcript: @<uuid> = that top-level file (never spans), @<agent-id> = that subagent's file.

@trap: — "which subagent am I?"

Scope: this is the subagent-only tool. A running subagent cannot read its own id from env; the top-level thread already has @main (env-based, no race, always correct) — reach for @trap only when you cannot name yourself. Invent a fresh marker, put it literally IN the csift command; csift finds the transcript whose shell tool_use carries it (Bash — or Windows' separate PowerShell tool, same command field). Grammar (enforced): exactly 3 CamelCase words + exactly 4 non-trivial trailing digits, hand-invented, context-independent — shaped like @trap:JollyShinyBrook4283, which is a RESERVED example csift hard-rejects (invent your own; never script-generate or reuse). TIMING: a subagent's transcript flushes per content block, so its launching command is on disk at dispatch and a first try resolves — that is the whole design. Diagnostic: from the MAIN thread a first use normally misses instead (the main record is an async flush of the completed message landing ~1-3.4s after dispatch, and csift beats it) — a miss therefore means EITHER you are the main thread (use @main) OR your marker was not literal; in neither branch is retrying @trap the answer. When @trap does resolve to the main transcript, csift says so on stderr. One-shot means one marker per identity question, not one per attempt (a fresh marker restarts the race). UNIQUENESS is conversation-wide: in a team/multi-subagent setting the marker must be unique across ALL concurrently-running agents, not just your own retries — a marker that lands in two transcripts (e.g. relayed to a peer in a message) errors AMBIGUOUS, fail-loud, never a silent wrong match. whoami @trap:<marker> returns the full upstream ancestry chain.

Labels (-t/--label · -T/--label-not) — dotted role.class.sub, 3 roles, 33 leaves

Selector = dot-segment prefix, THREE forms (v0.9.4): a bare ROLE (-t user) = the role's LLM-visible leaves only — the conversation as the model receives/produces it; a GLOB (-t 'user.*', quote it from the shell) = every leaf under the prefix, visibility ignored; an intermediate prefix (-t agent.tool = use+result, -t harness.compaction = summary+boundary) or a full leaf = its full set, a deliberate drill-down. No -t ⇒ all labels (drafts and boundaries stay searchable by default, with disclosure). -T EXCLUDES with the same grammar (effective set = includes minus excludes; a combination excluding everything it includes errors). Multi-label records emit once under the richest surviving view (an AUQ answer → user.answer; a SendMessage/spawn/<result> pulse → agent.communication.*; a slash-command-with-args → user.message rendered /name args). The complete rule is MECHANICAL, not a lookup table: JSON labels[] is always ordered richest-first, and the rendered view is simply the FIRST label in labels[] that survives your -t/-T — for any unlisted combination, read it off labels[]. Don't guess a record's leaf — run --count-by label to see the distribution.

user     .message   genuine human prose (incl. slash-command args, rendered `/name args`)
         .answer    AskUserQuestion answer (Q+options+answer unit)
         .rejection plan/tool reject + typed instruction
         .unsent    [not LLM-visible: outside `-t user`; reach via `-t user.unsent` or `-t 'user.*'`]
                    a SUPERSEDED draft: sent, esc-recalled, edited, re-sent — the original
                    stays on disk sharing the resend's parentUuid, OUTSIDE turn numbering,
                    never counted as user.message. LIMITS: a recalled-then-ABANDONED
                    message has no resend sibling and is undetectable; a QUEUED text
                    edited before dispatch never becomes a user record at all (its
                    queue-operation line is `.queued`, below)
         .queued    [not LLM-visible · GATED: parsed only under an explicit selector —
                    `-t user.queued` / `-t 'user.*'`; never by a bare scan, `-t user`,
                    or `--count-by label` without -t]
                    the human's text as it sat in the input QUEUE: a queue-operation
                    line with content — `[enqueue]` (typed while a turn ran), `[popAll]`
                    (recalled to the input box), `[remove · <reason>]` (consumed:
                    absorbed_mid_turn / delivered_to_agent). The label zone shows the
                    event. A queued <task-notification> / peer message is NOT the human
                    and carries no label; a content-less dequeue carries nothing. The
                    queue line has NO join key (measured: 4-6 keys, no promptId/uuid),
                    so `dispatched` is never asserted — a dispatched text simply also
                    exists as a later user.message; match by text if you must
agent    .message · .thinking (redacted → "[redacted thinking]") · .tool.use · .tool.result
         .thinking.narration   an API-issued one-sentence SUMMARY of the reasoning beside it
                               (tag hidden in the signature; renders "[narration summary]";
                               NOT the model's reasoning — pure reasoning = -t agent.thinking
                               -T agent.thinking.narration; excluded from verbatim replay)
         .communication.{inbox,sent,signal}   peer msgs — rendered `from ⇨ to` (self = owner)
harness  .notification.{workflow,monitor,subagent,background-command,task}  ← <task-notification>
                    (.subagent also carries the harness's agents-stopped notice
                    "N background agents were stopped by the user: …" — plain text,
                    no XML, not the human, never a turn opener, renders
                    "[subagent stopped] …"; .monitor = the Monitor tool's own
                    pulses and termination notices ONLY — since v0.10.0 a
                    `Background command "…"` pulse is always .background-command,
                    whatever its quoted name says)
         .compaction.{summary,boundary}   boundary renders its compactMetadata (trigger=…);
                    boundary is [not LLM-visible: outside `-t harness`; reach via
                    `-t harness.compaction` or the full leaf] — a metrics-only system record
         .command.{invocation,stdout} · .interrupt.{user,tool}
         .schedule.{wakeup,continuation} · .meta.{hook,loop,attachment}
         .meta.turn-duration   [not LLM-visible · GATED] the end-of-turn telemetry record:
                    `[turn duration: 1m 5s · durationMs=64911 messageCount=908
                    pendingBackgroundAgentCount=2]` — the structured body behind the
                    REPL's "Done in Ns" / "Waiting for N agents" lines (which never
                    land on disk). Present fields only; a turn that straddled a resume
                    gap reads as days, honestly. The pending counts cover background
                    agents and workflows ONLY: a turn that ended with a background SHELL
                    still running wrote no pending field at all (measured), so an EOT
                    record is never evidence that the session is done — that is
                    `csift status`
         .meta.away-summary    [not LLM-visible · GATED] the model-generated recap shown
                    when you return after 5+ minutes away (config-gated); verbatim text
         .meta.stop-hooks      [not LLM-visible · GATED] the Stop-hook execution ledger:
                    `[stop hooks: count=N errors=M prevented=false]` + one
                    `command (Nms)` line per hook — which hooks ran, how long, whether
                    one blocked the turn. NOT .meta.hook (that is text a hook INJECTED)
         .meta.snapshot        [not LLM-visible · GATED] a file-history snapshot
                    (`[file-history snapshot at <ts>: <path>@vN, …]`, every tracked
                    path) or delta (`[file-history delta at <ts>: <path>@vN
                    backup=<name>]`, one path's bump) — the v0.9.4 recover instrument,
                    searchable: "when did settings.json's version jump?"

LLM-VISIBILITY (v0.9.4, extended v0.10.0): SEVEN leaves are outside the bare-role selectors — user.unsent (a superseded draft is NOT in the surviving conversation: CC's own preservedMessages accounting excludes every draft uuid; say "not in the surviving conversation", never "the model never saw it" — a few drafts drew replies before the esc), harness.compaction.boundary (no message field at all), and the five v0.10.0 promoted leaves user.queued + harness.meta.{turn-duration,away-summary,stop-hooks,snapshot} — the same instrument: ZERO of the promoted line types carries a message{} field (every user/assistant record does), and CC's own source labels them REPL-render internals. Two instruments that do NOT decide visibility: parentUuid threading (a later user record names a turn_duration uuid as its parent — chain continuity, not delivery) and preservedMessages membership (a tail window listing these uuids at the same rate as messages). Everything else a role selector reaches is delivered-or-produced conversation. -t user therefore restores the 0.7-era contract ("what the human actually sent"): 0.9.2..0.9.3 briefly included drafts under it, which poisoned a real last-human-touch hook (a draft 12s before the real submit). isMeta is an AUTHORSHIP flag and isVisibleInTranscriptOnly a summary display flag — neither is a visibility instrument. Gated meta leaves: harness.meta.hook needs search --additional-context (or the superset --attachments); harness.meta.attachment (any OTHER attachment payload — edited_text_file, compact_file_reference, file snapshots …) needs --attachments or --count-by attachment — a default scan never parses attachment lines; an explicit show --line/--uuid address renders any of them flag-free. GATED PROMOTED LEAVES (v0.10.0): user.queued and harness.meta.{turn-duration,away-summary,stop-hooks,snapshot} need an EXPLICIT -t that reaches them — the full path, a glob (-t 'user.*', -t 'harness.*'), or the harness.meta prefix. A bare scan, a bare role, a -T-only filter and --count-by label without -t never parse those lines (most queued content is a duplicate automation pulse; every promoted line is a non-message line), so the default surface stays the conversation and costs nothing extra. A zero-match run without such a selector says so on stderr (JSON summary gated_leaves_unreached:true) — that absence does not cover the gated lines. show --line/--uuid renders any of them flag-free; --raw still prints the bytes. Glyphs: ◂ user · ▸ agent · ⚙ harness · · sibling · ▹ tool use↔result pair (unreturned → (no result — pending); orphan → (use not in scope)) · ⇨ comm direction. Turn boundary = genuine user ∨ AUQ answer ∨ typed rejection ∨ inbound peer message; slash-command wrappers, interrupts, <local-command-stdout>, compaction summaries never open a turn.

search — find round-trips

csift search PATTERN [target…] [-t SEL]… [-T SEL]… [-i] [--multiline] [--since W] [--until W]
  [--turn N|A..B|N..|-k] [--max-count ±N] [-c | -l | --count-by AXIS] [--raw] [--siblings]
  [--no-truncate] [--resolve-persisted] [--additional-context] [--attachments] [--sessions-from F] [--no-subagents] [--format json]

Empty "" pattern = pure filter. A hit returns the complete round-trip (tool_use with its result; user turn with reply; an answered AUQ as one Q+A unit). Terminal modes (mutually exclusive): -c prints one integer (EXCHANGES, --max-count drops added back) · -l prints the distinct owning session uuids, one per line, uncapped — pipes into --sessions-from - · --count-by AXIS prints a census (below).

• --count-by AXIS — a per-key census of the matched RECORDS along ONE closed axis (not a query language; a record whose several sections match still counts once): label (per leaf; a record counts under every leaf it carries THAT SURVIVES your -t/-T — a dual-labeled record never leaks its filtered-out twin into the keys, so -t user -T user.message --count-by label shows user.* keys only; with no filter that is the full label set — run with "" and no -t before guessing any -t) · tool (per tool name) · turn (ascending histogram) · session (per transcript) · pairing (paired | pending | orphan, joined by tool_use_id; rides the tool block through the communication views, so a frozen SendMessage is pending — "any pending tools?" needs no -t) · model (per assistant model — the raw message.model value; CC's <synthetic> placeholder, a fabricated stand-in assistant record such as an API-error notice, is reported verbatim) · attachment (per attachment payload type — IMPLIES the --attachments gate, so the census needs no separate flag) · version (per CC version stamp — where an upgrade landed mid-session) · result (per tool-result error state, ok | error — pairing answers "did a result come back", result answers "was it good": "any failed reads?" is search "" T --count-by result; an errored result also renders an inline [error] and carries JSON is_error). Records outside an axis's domain are excluded and the excluded count is reported.
• Excerpts are ~400-char match-centered fragments; when anything clipped, text prints a caution + JSON summary excerpts_truncated:true. Full text: --no-truncate (also un-clips JSON excerpt) or the hit's refetch.
• --siblings (zero-arg): also render the turn's other records — messages always, thinking≤2 · thinking.narration≤1 · tool.use≤3 · tool.result≤3 · harness≤2 per leaf — the caps apply to NON-matching context records only; your actual hits always render in full, so a block can legitimately show more than the cap count of same-leaf lines. Overflow prints (+N more · csift show @<id> --line A..B) — run it verbatim.
• --raw: the matched records' VERBATIM jsonl lines on the whole filter surface — stdout pure jsonl for jq (notes → stderr; sidecar-merged hits have no physical line and are omitted with a note). The answer to any unrendered-field question.
• --resolve-persisted: inline tool-results/<id>.txt files before matching (regex reaches externalized output); under --raw it affects matching only.
• --additional-context: ALSO scan hook-injected additionalContext (the attachment records a SessionStart/UserPromptSubmit/... hook writes — where <stamp>-style injected context lives). Off by default (machinery; echoes prompts/files wholesale). Hits surface under harness.meta.hook; the printed csift show @<id> --line N refetch renders one WITHOUT the flag (explicit address always works).
• --attachments: scan EVERY type:"attachment" record — a SUPERSET of --additional-context (hook payloads stay harness.meta.hook; every other payload surfaces under harness.meta.attachment with its VERBATIM payload JSON as the matchable text). Off by default: attachment lines are the bulk of many transcripts' bytes and embed whole files. An explicit show address renders any attachment record without the flag.
• --multiline sets (?s)(?m). Caveat: EVERY tool_use's matchable text is its name + the RE-SERIALIZED JSON input (not only AskUserQuestion's), so a real newline inside e.g. a Bash input.command is already the two-character sequence \n by match time — match the literal \\n; --multiline is correctly irrelevant there. It helps only where rendered text keeps real newlines (message text, thinking, tool_result bodies).
• OUTPUT GEOMETRY (text): exchanges emit oldest-first (stable chronological across every transcript in scope; undated exchanges last). Each exchange header opens with a STABLE id-prefix token <tok>·t<N> — <tok> = the first 8 chars of the owning transcript id, directly usable as an @ target, identical across invocations (a within-output collision lengthens the colliding group to 12 chars, then the full id; a teammate id renders whole); a subagent exchange carries (parent <first-8-of-owning-uuid>) on EVERY header. The head carries scope + match totals + direction (matches N exchanges · M sessions · oldest first[· showing earliest|latest K][· undated last]); the tail repeats the totals and adds integrity notes + refetch guidance; each over-long fragment marks its own truncation inline ((+N chars)). To limit output, prefer --max-count N (earliest N) or --max-count -N (latest N) over piping into head/tail — a capped run keeps every note; a pipe amputates one end of the ledger.
• Regex patterns WITH metacharacters are prefiltered too (v0.9.4): a necessity-only literal extraction (every branch of an alternation must demand one safe needle) lets search "TodoWrite.*legacy|legacy.*TodoWrite" scan at near-literal speed — no flag, no semantic change, matches are byte-identical.
• --max-count is SIGNED: N keeps the EARLIEST N of the chronological stream, -N the LATEST N, 0 = uncapped; the kept exchanges still emit oldest-first among themselves. The footer names the dropped side (N later|earlier dropped by --max-count).
• Superseded drafts (esc-edit resends: an opener replaced by a later same-parent sibling) stay OUTSIDE turn numbering but are fully searchable under their own leaf: a matching draft em

…(truncated)