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.
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.
