cc-transcript 14.11.1

Grep every Claude Code session you've ever run.

Grep every Claude Code session you've ever run. The lossless Rust parser reads Claude Code's on-disk JSONL at 169 MB/s; the compiled CLI greps it and renders one line per event, 25 ms cold.

Get started

uvx cc-transcript list

Every session is already on disk under ~/.claude/projects. list finds them newest first, and stats collapses one into a screenful:

Driving with an agent? Paste this:

/plugin marketplace add yasyf/cc-transcript
/plugin install cc-transcript@cc-transcript

The plugin's skill teaches Claude to answer "what did I ask you yesterday" from its own history, funneling through the CLI instead of reading raw JSONL.

No Claude Code? Point any agent at the CLI

Use `uvx cc-transcript` to investigate my Claude Code sessions: `list` finds
transcripts on disk, `stats` summarizes one, `grep` searches content, and `show`
renders one compact line per event. Start by listing my newest sessions and
summarizing the most recent one. Docs: https://yasyf.github.io/cc-transcript/

---

Use cases

Ask Claude what you asked Claude yesterday

Yesterday's session is a megabyte of JSONL, and pasting it into a chat blows the context window. Render the spine instead:

uvx cc-transcript show --signal --tail 20 ~/.claude/projects/<project>/<session>.jsonl

--signal keeps only the substantive user and assistant turns. One line per event, a few hundred tokens for the whole exchange. With the plugin installed, skip the command and ask Claude directly; its skill runs this funnel for you.

Find the session where you fixed that bug

The fix happened weeks ago, in one of a few hundred transcripts. Search them all:

uvx cc-transcript grep "TranscriptExpiredError" --project cc-transcript

Hits print under their transcript's path, each line carrying its raw event index; feed an index back into show --range to re-read the conversation around the fix. grep searches your newest 50 transcripts by default; --all takes it to every session on disk, and a no-match run exits 1 so it scripts cleanly.

Debug a token blowup from transcript evidence

A session burned through the context window and you want the culprit, not a guess. Rank the evidence:

uvx cc-transcript stats --per-file --project myapp

Each block reports text, thinking, and tool-io bytes plus per-tool call counts; the blowup stands out as an outsized tool io line. Then grep --tool <name> --with-result pins it to the exact calls.

Script it from Python

The CLI's funnel is four commands; your own tooling wants the events themselves. parse turns a path into a Transcript of typed lazy views, with the noise already dropped inside the engine:

from cc_transcript import NOISE_SPEC, discover, parse

transcript = parse(discover()[0], drop=NOISE_SPEC)
print(len(transcript.events), "events after the noise drop")

discover() lists every transcript on disk newest first, stream fans a whole corpus across the parse pool, and resolve finds one session by UUID. parse also reads OpenAI Codex CLI rollouts — hand it a path from ~/.codex/sessions and the same typed events come back. The getting-started guide builds this out to a composed filter and a sentiment score.

JSON output schema

show --json and grep --json emit JSONL, with one object per event. Each event uses the envelope {i, kind, meta, model, text, blocks, stop_reason, usage}; fields that do not apply to its kind are omitted. Every object in blocks has a type discriminator such as text, thinking, tool_use, tool_result, or fallback.

More in the docs

• The Python library turns a transcript into typed lazy views, a composed filter, and a score in a dozen lines.
• Filtering events covers composable clauses, specs, and the ready-made NOISE_SPEC.
• Sentiment scoring buckets conversations and scores them around any inference engine.
• Feedback mining runs detectors, confidence calibration, and LLM verdict passes over your corpus.
• The Rust engine is the implementation — parsing, filtering, scoring, and mining — its correctness pinned by hand-owned literals and golden fixtures.
• Codex rollouts make the parser two-provider: OpenAI Codex CLI sessions lower into the same typed events, with rollout discovery, subagent joins, and per-session lifecycle and token totals. list --provider codex finds them from the shell.
• API reference documents the complete typed surface, from TranscriptEvent to SessionActivity.

Read the docs for the full guide. Licensed under PolyForm Noncommercial 1.0.0.