cc-transcript 0.1.0

Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking.

cc-transcript

The shared transcript-parsing core extracted from cc-sentiment, now powering cc-pushback, cc-sentiment, and captain-hook. It parses Claude Code's on-disk JSONL transcripts into a typed superset event model — every entry type preserved, nothing dropped — so each consumer applies its own semantic filtering on top of one faithful representation.

The one property that makes it worth using: the parser is non-lossy. It never silently discards sidechains, synthetic turns, tool results, or unrecognized entry types; filtering is opt-in and lives in the consumer, not buried in the parser.

Install

uv add cc-transcript

Quickstart

Discover the transcripts on disk, parse one, and look at the events:

from cc_transcript import TranscriptDiscovery, parse_events, AssistantEvent, UserEvent

path, _mtime = TranscriptDiscovery.find_in(TranscriptDiscovery.find_transcripts()[0].parent)[0]
events = parse_events(path)

for event in events:
    match event:
        case UserEvent(text=text):
            print("user:", text[:80])
        case AssistantEvent(model=model, text=text):
            print(f"assistant ({model}):", text[:80])

Apply cc-sentiment's filtering rules to drop sidechains, synthetic turns, and junk:

from cc_transcript import apply_filters, SENTIMENT_FILTER

clean = list(apply_filters(events, SENTIMENT_FILTER))

What problems does this solve?

• One faithful parse, many consumers. Every project that reads Claude Code transcripts re-implements the same JSONL quirks (str-or-list content, tool results nested two ways, envelope-less mode markers). This is that parser, written once and typed strictly.
• Non-lossy by design. The event model is a superset: sidechains, <synthetic> turns, thinking blocks, and unrecognized entry types all survive parsing. You decide what to drop, via FilterConfig.
• Incremental ingestion. FileStateStore tracks per-file mtimes in SQLite (WAL, thread-safe) so re-runs only reparse changed files, and consumers compose their own writes in the same transaction.
• Pluggable backends. A pure-Python reference parser ships today; a Rust backend behind the same Backend protocol reaches parity in a later release.

Docs

Read the docs for the full guide and API reference.