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 codexfinds them from the shell. - API reference documents the complete typed surface, from
TranscriptEventtoSessionActivity.
Read the docs for the full guide. Licensed under PolyForm Noncommercial 1.0.0.
1 maintainer
Release files for cc-transcript 14.28.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cc_transcript-14.28.1.tar.gz | 12.4 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| cc_transcript-14.28.1-cp313-abi3-manylinux_2_28_x86_64.whl | CPython 3.13 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| cc_transcript-14.28.1-cp313-abi3-manylinux_2_28_aarch64.whl | CPython 3.13 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| cc_transcript-14.28.1-cp313-abi3-macosx_11_0_x86_64.whl | CPython 3.13 | abi3 | macOS 11.0+ x86-64 | Details |
| cc_transcript-14.28.1-cp313-abi3-macosx_11_0_arm64.whl | CPython 3.13 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 133.4 MB
Release files / cc_transcript-14.28.1.tar.gz
| Download URL | cc_transcript-14.28.1.tar.gz |
|---|---|
| Size | 12.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
220f30d68eaafb9027463d288be1d79f1f63db33748887cb6b0d7bd8c8efaeaf
|
|
BLAKE2b-256 checksum How to use checksums |
c913b57edcdf91f3bb34d38a0245907d5504e35261737a586d2ee70409d0a3c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / cc_transcript-14.28.1-cp313-abi3-manylinux_2_28_x86_64.whl
| Download URL | cc_transcript-14.28.1-cp313-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 30.7 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
ec64d4c25f003c0045e83c8716ce0a3e8c6ee7bef8a31913aabf57b5bf7022e8
|
|
BLAKE2b-256 checksum How to use checksums |
f785739422546f6d0efeeb04fd691d6845a4ca5a95ded8954169bba55d0be72e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / cc_transcript-14.28.1-cp313-abi3-manylinux_2_28_aarch64.whl
| Download URL | cc_transcript-14.28.1-cp313-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 30.1 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
f7b6faeb98aea0826d2c87f14604914f1a4024f8133a257b87d36bbba07cc272
|
|
BLAKE2b-256 checksum How to use checksums |
477e031dfe5c2d1cc9580a3df53b0c6c2f8b57d8c5cb2a158ce9138e3d1008d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / cc_transcript-14.28.1-cp313-abi3-macosx_11_0_x86_64.whl
| Download URL | cc_transcript-14.28.1-cp313-abi3-macosx_11_0_x86_64.whl |
|---|---|
| Size | 30.4 MB |
| Tags | CPython 3.13 abi3 macOS 11.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
f0ed0333aa48e3a883a8a6db807cc95200f72ad5f216e15e7d2b0468977f6c4b
|
|
BLAKE2b-256 checksum How to use checksums |
0bc4d4fc91d34874adf4125b3bbe54c561c5938eda356ef5cd6dae0464ea86cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / cc_transcript-14.28.1-cp313-abi3-macosx_11_0_arm64.whl
| Download URL | cc_transcript-14.28.1-cp313-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 29.9 MB |
| Tags | CPython 3.13 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fbad941cc4f59aa328987f1d69276a8b60463ce8b4858df213d2e621424f24bc
|
|
BLAKE2b-256 checksum How to use checksums |
aa728f80d49ffc7dddae2583e872770c2f3b2850761d8e55785f3ac9df33a2ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
