API Reference

Identity & digests

Branded ids, the universal EventRef handle, and the cross-language tool digest.

SessionId
EventUuid
ToolUseId
ToolDigest
EventRef: A resolvable reference to a transcript event.
canonical_json(): Serialize value per RFC 8785 (JSON Canonicalization Scheme).
tool_digest(): Digest a tool call’s content into the cross-language join key.

Events & parsing

The typed superset event model and the native parse entry points that produce it.

parse(): Parses one transcript into a ~cc_transcript.models.Transcript view.
stream(): Streams parsed transcripts for paths off the native parse pool.
Transcript: The parsed events of a single transcript file, backed by the native parse
EventList: A lazily-materializing sequence of transcript events over one parse output.
TranscriptEvent: The union of every typed event a parsed transcript can yield.
UserEvent: A user turn.
AssistantEvent: An assistant turn.
SystemEvent: A system entry, such as a hook summary or notice.
SystemDetail
StopHookSummary: The typed detail of a stop_hook_summary system entry.
HookInfo: One hook invocation recorded in a stop-hook summary.
CompactBoundary: The typed detail of a compact_boundary system entry.
PreservedSegment: The head/anchor/tail uuids of the segment preserved across a compaction.
PreservedMessages: The message uuids preserved across a compaction.
TurnDuration: The typed detail of a turn_duration system entry.
ModelRefusalFallback: The typed detail of a model_refusal_fallback system entry.
OtherSystemDetail: The catch-all detail for a system entry without a typed subtype.
ModeEvent: A mode or permission-mode change marker.
OtherEvent: Any recognized entry without a guaranteed conversational envelope.
AttachmentEvent: A harness attachment record — a hook firing, a queued command, or an
AttachmentDetail
HookSuccess: A hook that fired and exited cleanly, attached to the turn it ran on.
HookBlockingError: A hook that blocked the turn, carrying the structured blocking payload.
HookNonBlockingError: A hook that failed without blocking the turn.
HookCancelled: A hook the harness cancelled, typically on timeout.
HookAdditionalContext: Context a hook injected into the turn without blocking it.
AsyncHookResponse: The result of an asynchronously-executed hook, matched back by process id.
QueuedCommand: A user command queued for delivery to the agent, replayed as an attachment.
OtherAttachment: Any attachment whose type has no typed detail, carried verbatim.
PrintMessage: A conversational message lifted from a -p (print mode) result.
PrintResult: A parsed ‘claude -p –output-format json’ result.
ContentBlock
TextBlock: A text content block from a user or assistant message.
ThinkingBlock: An extended-thinking content block emitted by the assistant.
Question: One AskUserQuestion round lifted from a tool-use input’s questions array.
ToolUseBlock: An assistant request to invoke a tool.
ToolResultBlock: The result of a tool invocation, delivered in a user turn.
FallbackBlock: A marker that the assistant turn fell back from one model to another.
OtherBlock: Any assistant content block whose type is not yet modeled.
EntryMeta: Envelope metadata shared by the conversational transcript events.
CcVersion
Usage: Token usage and cache accounting for a single assistant turn or a -p (print mode) result.
ModelUsage: Per-model token usage and cost from a -p (print mode) result’s modelUsage map.
CacheCreation: The split of cache-creation input tokens by TTL bucket.
ServerToolUse: Server-side tool invocation counts billed within a turn.
Attribution: The plugin, skill, or MCP tool an assistant turn is attributed to.
ApiError: The upstream API error an assistant turn failed with.
McpServer: An MCP server entry from the -p init element.
Plugin: A plugin entry from the -p init element.
InitInfo: The session init snapshot from a -p system/init element.
tool_uses(): The event’s tool-use blocks, in content order.
thinking_chars(): The total character count of the event’s extended-thinking blocks.
parse_event(): Parse one decoded transcript-line mapping into its typed event view.
parse_events(): Parse raw transcript-line mappings into typed native events.
parse_events_from_bytes(): Parse a JSONL transcript byte buffer into typed native events.
parse_print_result(): Parse a ‘claude -p –output-format json’ payload into a ~cc_transcript.models.PrintResult.

Synthetic transcripts

Test-only builders that mint real native events by round-tripping envelope dicts through the parser.

synthetic_user_event(): Builds a native ~cc_transcript.models.UserEvent from text or content blocks.
synthetic_assistant_event(): Builds a native ~cc_transcript.models.AssistantEvent from text or content blocks.
user_line(): A type: user envelope; blocks are message.content entries.
assistant_line(): An type: assistant envelope; blocks are message.content entries.
text_block(): A text content block carrying text.
thinking_block(): A thinking content block carrying thinking.
tool_use(): A tool_use content block invoking name with input under id id.
tool_result(): A tool_result content block for tool_use_id; is_error marks a failed call.
meta_fields(): The envelope-level fields the parser lifts into ~cc_transcript.models.EntryMeta.
mode_line(): A mode/permission-mode envelope the parser lifts into ~cc_transcript.models.ModeEvent.
system_line(): A type: system envelope; fields carry the subtype-specific detail keys.
other_line(): An unmodeled-type envelope lifted into ~cc_transcript.models.OtherEvent; raw is the line.

Cost

Token pricing and the cost helper over assistant usage.

ModelPricing: USD-per-million-token rates for a model family.
CostBreakdown: The per-component and total USD cost of a single turn’s token usage.
cost_of(): Compute the USD cost of a turn’s token usage under a model’s rates.
cost_of_assistant(): Compute the cost of an assistant turn, or None when it carries no usage.
resolve_pricing(): Return the pricing row whose family key is a substring of model.
PRICING

Tool calls

One typed tool-call hierarchy shared by hook runtimes and the parser.

ToolCall
ToolCallBase: Common shape of every typed tool call.
parse_tool_call(): Parse a tool’s name and raw input into the typed hierarchy.
ToolInputError: A known tool’s input did not match its expected shape.
BashCall: A Bash/Execute shell invocation.
ReadCall: A Read of a file, optionally windowed.
WriteCall: A Write/Create of a whole file.
EditCall: An Edit replacement of old with new in one file.
MultiEditCall: A MultiEdit applying edits to one file, in order.
NotebookEditCall: A NotebookEdit replacing a cell’s source.
GlobCall: A Glob file-pattern search.
GrepCall: A Grep content search.
ExitPlanModeCall: An ExitPlanMode/ExitSpecMode plan submission.
SkillCall: A Skill invocation.
TaskCall: An Agent/Task subagent dispatch.
TaskCreateCall: A TaskCreate tracker entry.
TaskUpdateCall: A TaskUpdate tracker change.
WorkflowCall: A Workflow dynamic-orchestration dispatch.
OtherCall: A tool the platform does not type: unknown names, MCP tools, and — under
EditSpan: One replacement within a MultiEdit call, in application order.
Hunk: A before/after content pair lowered from an edit-shaped tool call.
hunks_of(): Lower an edit-shaped call to before/after hunks; () for the rest.
file_path_of(): The file a call targets, when it targets one.
mcp_parts(): Split an mcp__server__tool name into (server, tool), else None.
mcp_access(): Classify an MCP tool segment as "read" or "write" by its verbs.
TOOL_ALIASES
expand_tool_names(): Expand a pipe-separated tool spec to include alias and MCP bare spellings.
matches_names(): Whether actual is one of names, exactly or as an MCP tool suffix.
tool_name_matches(): Whether actual matches a pipe spec, honoring aliases and MCP suffixes.

Tool results

One typed per-tool result hierarchy over the record-level toolUseResult payload.

ToolResult
ToolResultBase: Common shape of every typed tool result.
parse_tool_result(): Parse a tool’s name and record-level toolUseResult into the typed hierarchy.
ToolResultError: A known tool’s result payload did not match its expected shape.
BashResult: A Bash/Execute execution result.
EditResult: An Edit result: the applied replacement and its structured patch.
WriteResult: A Write/Create result: the written content and its structured patch.
ReadResult: A Read result: the file payload and its content type.
TaskResult: A completed Agent/Task subagent run.
TaskLaunchResult: An in-flight Agent/Task launch (async or backgrounded subagent).
SkillResult: A Skill invocation result.
AskUserQuestionResult: An AskUserQuestion result: the rounds, the answers, and any annotations.
QuestionAnnotation: A reviewer’s annotation on one answered AskUserQuestion round.
TextResult: A plain-string tool result — denials and other unstructured payloads.
OtherResult: A tool result the platform does not type: unknown tools, untyped tools

Command lines

Parsed bash command lines — the one command-parsing layer, tree-sitter-backed.

Command: A single parsed shell command with executable, arguments, env vars, and redirects.
CommandLine: A full parsed bash command line, potentially containing multiple commands joined by operators.
CommandLineQuery: Predicate helpers for inspecting a parsed CommandLine. Obtain one via CommandLine.q.
Occurrence: One command of a CommandLine with its position and joining context.
Redirect: A shell redirect parsed from a bash command (e.g. > file.txt, 2>&1).
Word: One structural word of a parsed command (Command.words).
parse_command_line
command_prefixes(): Permission-style prefixes for each command of a shell command line.

Tool facts

Flat per-tool-use facts lifted from session activity, with command-prefix and MCP roll-ups.

ToolFact: One tool call flattened for analytics, lifted from a parsed transcript.
tool_facts(): Yields one ToolFact per tool call across every transcript file.
command_prefix_counts(): Counts every Bash command prefix across facts, most frequent first.
mcp_summary(): Summarizes MCP usage per server across facts.

Session activity

The spine — transcripts lifted into turns, tool uses, and first-class edits.

SessionActivity: A session’s transcript lifted into turns, tool uses, and edits.
Turn: One prompt-to-prompt span of a session.
ToolUse: One tool invocation lifted from a turn’s assistant events.
Edit: A file modification lowered from an edit-shaped tool call.
UserClassifier: Decides which ~cc_transcript.models.UserEvent objects open a turn.
native_user_classifier(): Whether a user event is a real prompt under native Claude Code semantics.
hunk_overlap(): The fraction of a.new’s non-empty lines present in b.old.
result_index(): Indexes tool results by the id of the tool use they answer.

Discovery & ingestion state

Finding transcripts on disk and tracking what has been ingested.

discover(): Every transcript under root, sorted by path.
resolve(): Locates session_id’s transcript on disk.
find_in(): Finds transcripts under directory newer than known mtimes.
subagent_paths(): Sidechain transcript files spawned by the session transcript at path.
TranscriptExpiredError: A session’s transcript file is gone from disk.
CLAUDE_PROJECTS_DIR

Codex sessions

The OpenAI Codex CLI provider — rollout discovery, subagent joins, and per-rollout session info over the ~/.codex/sessions tree.

CodexRollout: A rollout found in the codex sessions tree.
CodexSessionInfo: The identity, lifecycle, and usage of one codex rollout.
CodexUsage: Session-level token totals lowered from a codex rollout.
CodexPendingItem: A dangling tool call in the rollout’s open turn.
codex.sessions_root(): The codex sessions root, defaulting to ~/.codex/sessions.
codex.discover(): Every codex rollout under root, newest first.
codex.find_transcript(): Locates session_id’s rollout under the codex sessions tree.
codex.children_of(): Finds the direct child rollouts spawned by session_id.
codex.session_info(): The identity, lifecycle, and token usage of the rollout at path.

Watch

Live transcript tailing — byte-offset polling that yields each appended event exactly once.

Watcher: Tails every transcript under roots, one tick() per poll.
WatchEvent: One transcript event freshly appended to a watched file.

Activity probe

Disk-only session-activity verdicts over one transcript — captain-hook’s is_waiting oracle, read straight from the file.

activity_probe.SessionActivityProbe: The session-activity verdict over one transcript.
activity_probe.session_activity_probe(): Probes the transcript at path for session activity.

Heartbeats

Dispatch-heartbeat liveness records in the shared decisions.db ledger.

heartbeats.HeartbeatLog: The dispatch_heartbeats table in ~/.cc-transcript/decisions.db.

Notifications

The harness notification-delivery queue, replayed from a session’s events.

Notifications: The modeled state of a session’s harness notification-delivery queue.

Filtering

Filters-as-data — declarative specs and composable builders, executed in Rust at parse time or over materialized events.

FilterSpec: An ordered list of Clause rules applied to an event stream.
filterspec.Clause: One filter rule: when predicate holds, apply action.
filterspec.spec_to_json(): Serializes spec to the JSON contract consumed by the Rust backend.
apply_spec(): Yields the already-materialized events that survive every DROP clause of spec.
annotate_spec(): Yields (event, labels) for events surviving spec, with TAG labels, streaming lazily.
keep(): Returns whether event survives every DROP clause of spec.
labels_for(): Returns the TAG labels spec records for event, in clause order.
build_spec(): Flattens Clause / tuple[Clause, ...] fragments into a FilterSpec.
keep_only(): Drops every event whose kind is not in kinds.
drop_synthetic(): Drops assistant events with the <synthetic> model.
drop_empty(): Drops blank events of one kind.
drop_sidechain(): Drops sidechain events; except_assistants keeps assistant sidechains.
drop_meta_flag(): Drops events whose EntryMeta boolean flag is set.
drop_compacted(): Drops compaction-summary and transcript-only entries.
drop_entrypoints(): Drops events whose meta.entrypoint is in entrypoints.
drop_junk(): Drops events matching any group in the named JUNK_CATEGORIES.
drop_phrases(): Drops events whose normalized text is one of phrases.
drop_short(): Drops events with at most max_words whitespace-split words.
NOISE_SPEC
filterspec.JUNK_CATEGORIES
USERS
ASSISTANTS
RESUME_PHRASE_SET
TRIVIAL_ACK_SET
STRUCTURAL_NOISE_RE
JUNK_USER_MESSAGE_RE

Context windows

Refs-not-prose context — persisted EventRefs plus previews that hydrate back to full fidelity.

ContextWindow: The turns around an anchor event, persisted as refs plus previews.
HydratedWindow: A context window resolved back to its real turns.
TurnRef: A reference to one turn: resolvable refs plus a capture-time preview.
capture_window(): Capture the turns around anchor as a live, full-fidelity window.
SchemaError: Persisted context data does not carry a known schema version.

Rendering

The one renderer — budget-bounded turns, tool calls, and sessions; truncation happens only here.

Budget: Render-time character budgets — the only place the platform cuts content.
render_tool_call(): Render a typed tool call, clipping each content piece to the tool budget.
render_turn(): Render one turn: the prompt, assistant prose, and every tool call, in order.
render_session(): Render every turn of a session under budget, separated by blank lines.

Evidence

Incorrect-edit and correction harvest, with a read-only git pickaxe fallback.

harvest_pairs(): Harvests incorrect-edit/correction pairs around anchor.
match_corrections(): Session corrections for edit, ranked by overlap descending.
git_corrections(): Corrections to hunk found in repo’s git history.
record_harvest(): Records pairs harvested around anchor into the shared ledger.
CandidatePair: One incorrect-edit candidate and its best-matching correction.
GitFix: A correction found in git history rather than the session.

Query

The transcript query surface — sessions, tool-call queries, file refs, subagent recursion, and the recursive deep view.

Session: An immutable windowed view of a session’s turns.
ToolCallQuery: A chainable filter over a window’s tool calls.
FileRef: A file path carried by a tool call, with glob and prefix matching.
SubagentSession: One Task dispatch joined to its sidechain transcript.
SubagentIndex: The subagent dispatches of a session window.
DeepView: The recursive union of a session and every transcript reachable from it.
DeepSession: One transcript reached by Session.walk().

Decisions

The unified decision ledger, joined to tool calls by content digest.

DecisionLog: The decisions ledger at ~/.cc-transcript/decisions.db.
Decision: One row of the decision ledger.
Action
DECISIONS_DDL

Corrections

The cross-language correction ledger — incorrect edits paired with the fix that later overwrote them, joined to tool calls by content digest.

CorrectionLog: The corrections ledger at ~/.cc-transcript/corrections.db.
Correction: One incorrect edit and the correction that overwrote it.
Origin
CORRECTIONS_DDL

Disk truth

Typed reader for cc-review’s session-activity export.

DiskTruth: A session’s disk-level activity exported from cc-review.
TreeTurn: One Claude prompt-to-stop window bracketed by working-tree snapshots.
FileAttribution: One file’s attribution ranges within one review version.
AttributionRange: An inclusive span of new-side diff lines attributed to one turn.
load_export(): Parse a cc-review export activity payload.
export_activity(): Export session_id’s disk truth by shelling out to cc-review.

NLP

The UDPipe-backed token substrate — typed tokens with form, lemma, POS, codepoint span, polarity, and negation.

nlp.analyze(): Analyze text into typed Token objects via the embedded UDPipe model.
nlp.Token: One analyzed token: its surface, linguistics, source span, and sentiment.

Sentiment

Conversation buckets and a composable score spec around any inference engine.

sentiment.bucket_events
sentiment.ConversationEvent: The conversational subset of the event spine that sentiment scoring consumes.
sentiment.ConversationBucket: A session’s conversational events grouped into one fixed-width time window — the unit that gets scored.
sentiment.ConversationBucketer: Groups conversational transcript events into per-session, time-aligned buckets worth scoring.
sentiment.BucketKey: Stable identity of a ConversationBucket: its session and bucket index.
sentiment.BucketIndex
sentiment.BUCKET_MINUTES
sentiment.extract_bucket_keys(): Returns the BucketKey of every scorable bucket in events.
sentiment.SentimentScore
sentiment.InferenceEngine
sentiment.FilteredEngine: Wraps an InferenceEngine with a ScoreSpec: short-circuit
sentiment.ScoreSpec: An ordered list of ScoreStage applied around model inference.
sentiment.ScoreStage
sentiment.build_score_spec(): Assembles stages into a ScoreSpec for the engine to apply around inference.
sentiment.flag_frustration(): Composes the short-circuit stage that pins a frustrated message to score before inference.
sentiment.clamp_positive(): Composes the post-process stage that lowers a top score on a short message lacking positive lexicon.
sentiment.clamp_resume(): Composes the post-process stage that neutralizes a bare resume phrase to a middling score.
sentiment.demote_mild_irritation(): Composes the post-process stage that softens a non-hostile mild-impatience message off the floor score.
sentiment.Lexicon: Surface-form token polarity: coding-domain overrides layered over AFINN.

Mining

Feedback detectors, confidence calibration, candidate filtering, and the feedback store.

mining.MiningSignal: A neutral fact mined from a transcript, ready for an app to map to a candidate.
mining.CandidateSignal: A confidence verdict on a mined fact, with the reasons that produced it.
mining.Confidence: A de-noising score in the closed interval [0, 1]; higher is more trustworthy.
mining.NOISE_FLOOR
mining.MiningSpec: The full declarative mining policy the Rust executor interprets.
mining.mine(): Mines every MiningSignal from already-parsed transcript events.
mining.mining_spec_to_json(): Serializes spec to the JSON contract consumed by the Rust mining executor.
mining.DENIAL_PREFIX
mining.DENIAL_KIND_USER_REJECTED
mining.DENIAL_KIND_PERMISSION_RULE
mining.USER_SAID_MARKER
mining.USER_SAID_TRAILER
mining.ANSWERED_PREFIX
mining.ANSWERED_TRAILER
mining.SourceKind: A descriptive category for a mined feedback fact.
mining.FeedbackCandidate: A single piece of developer pushback extracted from a transcript.
mining.DedupKey: A content-derived SHA-256 key that makes feedback ingestion idempotent.
mining.dedup_key(): Returns the stable dedup key for parts.
mining.ReviewComment: A single inline review comment parsed from a code-review message.
mining.ReviewFormat
mining.FeedbackStore: Persistent store for collected feedback over the native store engine.
mining.StoreSchema: One complete exact v1 feedback-store schema.
mining.TransactionConflictError: A write attempted while another task’s transaction holds the connection.
mining.Stats: A snapshot of ingestion progress.
mining.sample_windows(): Sample up to n triggerless context windows as steering negatives.

Judge

LLM verdict passes over the mined corpus — structured judging, audits, and eval math.

judge.VerdictLike: The structural shape a judge’s verdict must expose to be persisted.
judge.run_verdicts(): Runs judge over every row’s prompt and persists each verdict as it lands.
judge.sample_audit(): Draws the deterministic stratified audit sample over judged rows.
judge.Metrics: The full mechanical evaluation of one prompt version.
judge.AuditEstimate: One binomial estimate from audited rows.
judge.exact_upper_bound(): Returns the exact (Clopper-Pearson) one-sided upper confidence bound.
judge.GoldenRow: One frozen, hand-labeled row of the golden regression set.
judge.golden_result(): Gates one pass’s verdicts against the frozen golden fixture.
judge.flip_pairs(): Compares two verdict passes row by row.
judge.structured_judge(): Returns a prompt-to-verdict callable that plugs into run_verdicts().
judge.resolved_model(): The concrete model name the active backend runs for an abstract tier.