Events & parsing

parse()

Parses one transcript into a ~cc_transcript.models.Transcript view.

Usage

parse(
    source,
    *,
    drop=None,
)

Parameters

source: Path | bytes: A transcript file path, or raw JSONL bytes. A path parse carries the file’s path and mtime on the view; a bytes parse has path=None.
drop: FilterSpec | None = None: Optional ~cc_transcript.FilterSpec applied during parsing; events it drops never materialize as Python objects.

Returns

Transcript: The parsed transcript view.

Raises

OSError: When a path source cannot be read.

Example

>>> transcript = parse(path, drop=NOISE_SPEC)
>>> [event.meta.uuid for event in transcript.events]

stream()

Streams parsed transcripts for paths off the native parse pool.

Usage

Source

stream(paths, *, drop=None, prefetch=4)

Files parse in parallel with prefetch results buffered ahead of the consumer; an unreadable file — including one pruned between discovery and parse — is skipped without disturbing the rest of the batch. Order follows parse completion, not the input order.

Parameters

paths: Iterable[Path]: The transcript files to parse.
drop: FilterSpec | None = None: Optional ~cc_transcript.FilterSpec applied during parsing; events it drops never materialize as Python objects.
prefetch: int = 4: Parsed files to hold ready ahead of the consumer.

Yields

One: Transcript: class:~cc_transcript.models.Transcript per readable input path.

Example

>>> for transcript in stream(discover(), drop=NOISE_SPEC):
...     print(transcript.path, len(transcript.events))

Transcript

The parsed events of a single transcript file, backed by the native parse

Usage

Transcript()

output; events materializes lazy views on access.

One parse owns one Arc<Vec<Entry>> shared by every view, so retaining any view keeps the whole parse’s entries alive; the live ~watch.WatchEvent stream is exempt (one-entry Arc each).

Attributes

path: pathlib.Path | None: The transcript’s path on disk; None for a bytes parse.
mtime: builtins.float: The transcript’s modification time when parsed.
provider: Literal["claude", "codex"]: The transcript’s source provider: “claude” or “codex”.
events: EventList: The parsed events, in file order.

EventList

A lazily-materializing sequence of transcript events over one parse output.

Usage

EventList(self, index: int) -> models.TranscriptEvent
EventList(self, index: slice) -> list[models.TranscriptEvent]

Implements the immutable collections.abc.Sequence interface — indexing, slicing, iteration, len, in, reversed(), index, and count — and is registered as a virtual Sequence. copy() returns a plain list, and == is elementwise against any list, tuple, or EventList (list(events) == events). Views materialize fresh on each access, so identity across accesses is not guaranteed by design (events[0] is events[0] is False). copy.copy and copy.deepcopy return the immutable list itself; pickle is unsupported. Like the Transcript it comes from, retaining any event pins the whole parse.

TranscriptEvent

The union of every typed event a parsed transcript can yield.

UserEvent

A user turn.

Usage

UserEvent()

Attributes

meta: EntryMeta: The entry envelope metadata.
text: builtins.str: The joined text of the turn.
blocks: tuple[models.ContentBlock, …]: The parsed content blocks, including tool results.
interrupted: builtins.bool: Whether the turn is a user interruption.
is_agent_injected: builtins.bool: Whether the turn is an agent-injected relay banner — a teammate-message digest, scheduled-task banner, or foreign-agent header — rather than an authored prompt.
prompt_id: builtins.str | None: The client-assigned id of the prompt this turn belongs to, or None.
prompt_source: builtins.str | None: How the prompt was submitted, e.g. typed, queued, system, or sdk, or None when absent.
queue_priority: builtins.str | None: The queue priority recorded for a queued prompt, or None.
image_paste_ids: tuple[int, …] | None: The paste ids of images attached to the turn, or None when the turn carries no image-paste marker.
source_tool_use_id: ids.ToolUseId | None: The id of the tool-use that produced this turn, when the turn originates from a tool result, else None.
source_tool_assistant_uuid: ids.EventUuid | None: The uuid of the assistant entry whose tool produced this turn, else None.
mcp_meta: collections.abc.Mapping[str, Any] | None: The verbatim mcpMeta payload attached to the turn, or None.
permission_mode: builtins.str | None: The permission mode in effect for the turn, or None.
interrupted_message_id: builtins.str | None: The API message id (msg_...) of the assistant turn this interruption cut short, or None. Set from the raw interruptedMessageId field; it names the interrupted assistant’s API message, not a transcript event uuid.

AssistantEvent

An assistant turn.

Usage

AssistantEvent()

Attributes

meta: EntryMeta: The entry envelope metadata.
model: builtins.str: The model that produced the turn, e.g. <synthetic>.
text: builtins.str: The joined text of the turn.
blocks: tuple[models.ContentBlock, …]: The parsed content blocks, including thinking and tool uses.
stop_reason: builtins.str | None: The model’s stop reason, when present.
usage: Usage | None: Token usage for the turn, or None when the entry carries no usage (older transcripts, API-error messages).
request_id: builtins.str | None: The API request id that produced the turn, or None.
forked_from: builtins.str | None: The id of the message this turn was forked from, or None.
attribution: Attribution | None: The plugin/skill/MCP attribution for the turn, or None when the entry carries no attribution field.
api_error: ApiError | None: The upstream API error the turn failed with, or None when the entry is not an API-error message.

SystemEvent

A system entry, such as a hook summary or notice.

Usage

SystemEvent()

Attributes

meta: EntryMeta: The entry envelope metadata.
subtype: builtins.str: The system entry’s subtype.
content: builtins.str | None: The entry’s text content, when present.
level: builtins.str | None: The entry’s severity level, when present.
detail: models.SystemDetail: The typed detail for the subtype — a StopHookSummary, CompactBoundary, TurnDuration, or ModelRefusalFallback when recognized, else an OtherSystemDetail carrying the full payload. Always set.

SystemDetail

SystemDetail=( StopHookSummary | CompactBoundary | TurnDuration | ModelRefusalFallback | OtherSystemDetail )

StopHookSummary

The typed detail of a stop_hook_summary system entry.

Usage

StopHookSummary()

Attributes

hook_count: builtins.int | None: The number of hooks that ran.
hook_infos: tuple[HookInfo, …]: The per-hook command and duration records.
hook_errors: tuple[str, …]: The error strings raised by hooks.
hook_additional_context: tuple[str, …]: The extra context strings hooks contributed.
prevented_continuation: builtins.bool: Whether a hook blocked the turn from continuing.
stop_reason: builtins.str | None: The reason the turn stopped, when recorded.
has_output: builtins.bool: Whether the hooks produced output.
tool_use_id: ids.ToolUseId | None: The tool-use id the summary is tied to, when present.

HookInfo

One hook invocation recorded in a stop-hook summary.

Usage

HookInfo()

Attributes

command: builtins.str: The hook command that ran.
duration_ms: builtins.int | None: The hook’s wall-clock duration in milliseconds, when recorded.

CompactBoundary

The typed detail of a compact_boundary system entry.

Usage

CompactBoundary()

Attributes

trigger: builtins.str | None: What triggered the compaction, such as manual or auto.
pre_tokens: builtins.int | None: The context token count before compaction.
post_tokens: builtins.int | None: The context token count after compaction.
duration_ms: builtins.int | None: The compaction’s wall-clock duration in milliseconds.
cumulative_dropped_tokens: builtins.int | None: The session’s running total of tokens dropped by compactions.
pre_compact_discovered_tools: tuple[str, …]: The tool names discovered before compaction.
preserved_segment: PreservedSegment | None: The head/anchor/tail segment preserved, when recorded.
preserved_messages: PreservedMessages | None: The preserved message uuids, when recorded.
logical_parent_uuid: ids.EventUuid | None: The uuid the post-compaction thread logically continues from.
precomputed: builtins.bool | None: Whether the compaction was precomputed, when recorded.

PreservedSegment

The head/anchor/tail uuids of the segment preserved across a compaction.

Usage

PreservedSegment()

Attributes

head_uuid: ids.EventUuid | None: The first preserved event’s uuid.
anchor_uuid: ids.EventUuid | None: The anchor event’s uuid.
tail_uuid: ids.EventUuid | None: The last preserved event’s uuid.

PreservedMessages

The message uuids preserved across a compaction.

Usage

PreservedMessages()

Attributes

anchor_uuid: ids.EventUuid | None: The anchor event’s uuid.
uuids: tuple[ids.EventUuid, …]: The uuids of the preserved messages, in order.
all_uuids: tuple[ids.EventUuid, …]: The uuids of every message considered for preservation, in order.

TurnDuration

The typed detail of a turn_duration system entry.

Usage

TurnDuration()

Attributes

duration_ms: builtins.int | None: The turn’s wall-clock duration in milliseconds.
message_count: builtins.int | None: The number of messages in the turn.
pending_workflow_count: builtins.int | None: The workflows still pending, when recorded.
pending_background_agent_count: builtins.int | None: The background agents still pending, when recorded.

ModelRefusalFallback

The typed detail of a model_refusal_fallback system entry.

Usage

ModelRefusalFallback()

Attributes

api_refusal_category: builtins.str | None: The refusal category the API reported, when present.
api_refusal_explanation: builtins.str | None: The refusal explanation the API reported, when present.
trigger: builtins.str | None: What triggered the fallback.
direction: builtins.str | None: The fallback direction.
original_model: builtins.str | None: The model that refused.
fallback_model: builtins.str | None: The model fallen back to.
retracted_message_uuids: tuple[ids.EventUuid, …]: The uuids of messages retracted by the fallback.
refused_user_message_uuid: ids.EventUuid | None: The user message uuid that drew the refusal, when present.

OtherSystemDetail

The catch-all detail for a system entry without a typed subtype.

Usage

OtherSystemDetail()

Carries the entry’s full decoded payload verbatim, so no system entry is lossy regardless of subtype.

Attributes

raw: collections.abc.Mapping[str, Any]: The entry’s full decoded payload.

ModeEvent

A mode or permission-mode change marker.

Usage

ModeEvent()

These entries carry only a session id on disk — no uuid, timestamp, or other envelope fields — so they hold a session_id directly rather than an EntryMeta.

Attributes

session_id: ids.SessionId: The session whose mode changed.
channel: Literal["mode", "permission-mode"]: Which mode channel changed.
value: builtins.str: The new mode value.

OtherEvent

Any recognized entry without a guaranteed conversational envelope.

Usage

OtherEvent()

Covers ai-title, last-prompt, summary, queue-operation, file-history-snapshot, and similar entry types whose shape carries no EntryMeta. Attachments are typed separately as AttachmentEvent.

Attributes

type: builtins.str: The entry’s type field.
raw: collections.abc.Mapping[str, Any]: The entry’s full decoded payload.

AttachmentEvent

A harness attachment record — a hook firing, a queued command, or an

Usage

AttachmentEvent()

informational injection — carrying the full envelope it was written with.

Recognized attachment types carry their typed AttachmentDetail; every other type carries the full record verbatim under OtherAttachment, so no attachment is lossy.

Attributes

meta: EntryMeta: The entry envelope metadata.
attachment_type: builtins.str: The raw attachment.type string, e.g. hook_success.
detail: models.AttachmentDetail: The typed attachment payload.

AttachmentDetail

HookSuccess

A hook that fired and exited cleanly, attached to the turn it ran on.

Usage

HookSuccess()

Attributes

hook_name: builtins.str | None: The hook matcher that fired, e.g. PostToolUse:Bash, or None.
hook_event: builtins.str | None: The lifecycle event that triggered it, e.g. PostToolUse, or None.
tool_use_id: ids.ToolUseId | None: The tool-use the hook ran against, or None for lifecycle hooks.
command: builtins.str | None: The hook command line, or None.
content: builtins.str | None: The additional context the hook injected, or None.
stdout: builtins.str | None: The hook’s captured stdout, or None.
stderr: builtins.str | None: The hook’s captured stderr, or None.
exit_code: builtins.int | None: The hook’s exit status, or None.
duration_ms: builtins.int | None: The hook’s wall-clock duration in milliseconds, or None.

HookBlockingError

A hook that blocked the turn, carrying the structured blocking payload.

Usage

HookBlockingError()

Attributes

hook_name: builtins.str | None: The hook matcher that fired, or None.
hook_event: builtins.str | None: The lifecycle event that triggered it, or None.
tool_use_id: ids.ToolUseId | None: The tool-use the hook ran against, or None.
blocking_error: collections.abc.Mapping[str, Any] | None: The verbatim blockingError payload, or None.

HookNonBlockingError

A hook that failed without blocking the turn.

Usage

HookNonBlockingError()

Attributes

hook_name: builtins.str | None: The hook matcher that fired, or None.
hook_event: builtins.str | None: The lifecycle event that triggered it, or None.
tool_use_id: ids.ToolUseId | None: The tool-use the hook ran against, or None.
command: builtins.str | None: The hook command line, or None.
stdout: builtins.str | None: The hook’s captured stdout, or None.
stderr: builtins.str | None: The hook’s captured stderr, or None.
exit_code: builtins.int | None: The hook’s exit status, or None.
duration_ms: builtins.int | None: The hook’s wall-clock duration in milliseconds, or None.

HookCancelled

A hook the harness cancelled, typically on timeout.

Usage

HookCancelled()

Attributes

hook_name: builtins.str | None: The hook matcher that fired, or None.
hook_event: builtins.str | None: The lifecycle event that triggered it, or None.
tool_use_id: ids.ToolUseId | None: The tool-use the hook ran against, or None.
command: builtins.str | None: The hook command line, or None.
duration_ms: builtins.int | None: How long it ran before cancellation, or None.
timed_out: builtins.bool | None: Whether the cancellation was a timeout, or None.
timeout_ms: builtins.int | None: The configured timeout in milliseconds, or None.

HookAdditionalContext

Context a hook injected into the turn without blocking it.

Usage

HookAdditionalContext()

Attributes

hook_name: builtins.str | None: The hook matcher that fired, or None.
hook_event: builtins.str | None: The lifecycle event that triggered it, or None.
tool_use_id: ids.ToolUseId | None: The tool-use the hook ran against, or None.
content: tuple[str, …]: The injected context lines, in order.

AsyncHookResponse

The result of an asynchronously-executed hook, matched back by process id.

Usage

AsyncHookResponse()

Attributes

hook_name: builtins.str | None: The hook matcher that fired, or None.
hook_event: builtins.str | None: The lifecycle event that triggered it, or None.
process_id: builtins.str | None: The async execution’s process id, or None.
stdout: builtins.str | None: The hook’s captured stdout, or None.
stderr: builtins.str | None: The hook’s captured stderr, or None.
exit_code: builtins.int | None: The hook’s exit status, or None.
response: collections.abc.Mapping[str, Any] | None: The verbatim response payload, or None.

QueuedCommand

A user command queued for delivery to the agent, replayed as an attachment.

Usage

QueuedCommand()

Attributes

prompt: builtins.str | None: The queued command’s prompt text, or None when it carries no plain-string prompt (e.g. an image-paste payload).
command_mode: builtins.str | None: How the command was queued, e.g. prompt or task-notification, or None.

OtherAttachment

Any attachment whose type has no typed detail, carried verbatim.

Usage

OtherAttachment()

Covers the many informational attachment types (skill/tool/agent listings, reminders, plan-mode markers, file references, and anything future) whose shape is not further decomposed, mirroring OtherSystemDetail.

Attributes

raw: collections.abc.Mapping[str, Any]: The attachment entry’s full decoded payload.

PrintMessage

A conversational message lifted from a -p (print mode) result.

Usage

PrintMessage()

Unlike on-disk events it carries no EntryMeta — the -p element shape lacks timestamp/parentUuid — so it holds only role, model, text, blocks, and the ids that are present.

Attributes

role: Literal["user", "assistant"]: The author of the message, either “user” or “assistant”.
model: builtins.str | None: The model that produced the message, when present.
text: builtins.str: The flattened text of the message.
blocks: tuple[models.ContentBlock, …]: The structured content blocks of the message.
uuid: ids.EventUuid | None: The message’s event uuid, when present.
session_id: ids.SessionId: The session the message belongs to.
id: builtins.str | None: The API message id, when present (assistant messages carry one).
usage: Usage | None: The message’s token usage, when present (assistant messages carry one).

PrintResult

A parsed ‘claude -p –output-format json’ result.

Usage

PrintResult()

Holds the billing/usage/structured-output payload, the init snapshot, and the conversational messages. Reuses the shared Usage model; not a TranscriptEvent.

Attributes

total_cost_usd: builtins.float: The total cost in USD for the run.
model_usage: collections.abc.Mapping[str, ModelUsage]: Per-model usage and cost, keyed by model name.
usage: Usage: The aggregate token usage for the run.
structured_output: collections.abc.Mapping[str, Any] | None: The structured output payload, when present.
num_turns: builtins.int: The number of turns in the run.
is_error: builtins.bool: Whether the run ended in an error.
result: builtins.str | None: The final result text, when present.
session_id: ids.SessionId: The session the run belongs to.
fast_mode_state: builtins.str | None: The fast-mode state reported for the run, when present.
stop_reason: builtins.str | None: The reason the run stopped, when present.
permission_denials: tuple[collections.abc.Mapping[str, Any], …]: The permission denials recorded during the run.
init: InitInfo | None: The session init snapshot, when present.
messages: tuple[PrintMessage, …]: The conversational messages of the run.

ContentBlock

TextBlock

A text content block from a user or assistant message.

Usage

TextBlock()

Attributes

text: builtins.str: The block’s literal text.

ThinkingBlock

An extended-thinking content block emitted by the assistant.

Usage

ThinkingBlock()

Attributes

thinking: builtins.str: The model’s thinking text.

Question

One AskUserQuestion round lifted from a tool-use input’s questions array.

Usage

Question()

Attributes

question: builtins.str: The prompt text shown to the user.
header: builtins.str | None: The round’s short header, or None when the input omits one.
multi_select: builtins.bool: Whether the round accepted more than one selection.
labels: tuple[str, …]: The option labels offered, in presentation order.

ToolUseBlock

An assistant request to invoke a tool.

Usage

ToolUseBlock()

Attributes

id: ids.ToolUseId: The tool-use identifier referenced by the matching result.
name: builtins.str: The tool’s name.
input: collections.abc.Mapping[str, Any]: The tool’s input arguments, preserved verbatim. v14: a read-only ~models.ReadOnlyDict — the view is immutable, so the input cannot be mutated out of step with call/digest. It stays a dict (serializes and canonicalizes like one); only the top level is frozen, so nested containers keep their plain-JSON types.

Attributes

Name	Description
call	The block parsed into the typed tool-call hierarchy.
digest	The cross-language content digest of this call.
file_path	The raw file_path input argument when it is a string, else None.
input	The tool’s input arguments, as a read-only mapping (v14: immutable view).
questions	The AskUserQuestion rounds lifted from the questions input array, or None.

call

The block parsed into the typed tool-call hierarchy.

call: tools.ToolCall

Strict: a known tool whose input is malformed raises ~tools.ToolInputError.

digest

The cross-language content digest of this call.

digest: ids.ToolDigest

file_path

The raw file_path input argument when it is a string, else None.

file_path: builtins.str | None

Mirrors the Rust parse-layer lift in rust/crates/core/src/parse.rs: the value is read verbatim from the input for every tool, and a non-object input or a non-string value reads as None. Mining denial evidence consumes this uniform lift rather than the type-dispatched ~tools.file_path_of().

input

The tool’s input arguments, as a read-only mapping (v14: immutable view).

input: collections.abc.Mapping[str, Any]

questions

The AskUserQuestion rounds lifted from the questions input array, or None.

questions: tuple[Question, …] | None

The native getter reads the typed tool call’s questions; a non-object input reads as None.

ToolResultBlock

The result of a tool invocation, delivered in a user turn.

Usage

ToolResultBlock()

Attributes

tool_use_id: ids.ToolUseId: The id of the originating tool-use block.
content: builtins.str: The result text, flattened from string or block content.
is_error: builtins.bool: Whether the tool reported a failure.
is_async: builtins.bool: Whether the originating tool ran asynchronously — computed at the parse layer from tool_use_result’s isAsync marker, then stored (like UserEvent.interrupted).
tool_use_result: collections.abc.Mapping[str, Any] | str | None: The record-level toolUseResult payload verbatim — a mapping for structured results, a plain string for denials, or None when the record carried none. Pass a tool name and this payload to ~tools.parse_tool_result() for the typed result. v14: a structured payload is a read-only ~models.ReadOnlyDict, like ToolUseBlock.input.
denial_kind: builtins.str | None: The tool-denial kind, computed at the parse layer — the record-level toolDenialKind (user-rejected for a human rejection, permission-rule for a hook/guard block) when present, else user-rejected when this error block carries the legacy denial banner, else None.

FallbackBlock

A marker that the assistant turn fell back from one model to another.

Usage

FallbackBlock()

Claude Code records this when a turn switches models mid-stream; it carries no message content, only the two model names.

Attributes

from_model: builtins.str: The model the turn started on.
to_model: builtins.str: The model the turn fell back to.

OtherBlock

Any assistant content block whose type is not yet modeled.

Usage

OtherBlock()

The escape hatch that keeps an unrecognized block from crashing the parser as Claude Code’s transcript format evolves, mirroring OtherEvent.

Attributes

type: builtins.str: The block’s type field.
raw: collections.abc.Mapping[str, Any]: The block’s full decoded payload.

EntryMeta

Envelope metadata shared by the conversational transcript events.

Usage

EntryMeta()

Attributes

uuid: ids.EventUuid: The entry’s unique identifier.
parent_uuid: ids.EventUuid | None: The parent entry’s id, or None for roots.
session_id: ids.SessionId: The session this entry belongs to.
timestamp: datetime.datetime: The entry’s timezone-aware timestamp.
cwd: builtins.str | None: The working directory recorded for the entry.
git_branch: builtins.str | None: The git branch recorded for the entry.
cc_version: models.CcVersion | None: The Claude Code version that wrote the entry.
is_sidechain: builtins.bool: Whether the entry belongs to a subagent sidechain.
is_meta: builtins.bool: Whether the entry is a meta entry injected by the client.
entrypoint: builtins.str | None: The entrypoint that produced the entry, e.g. cli.
is_compact_summary: builtins.bool: Whether the entry is a compaction summary.
is_visible_in_transcript_only: builtins.bool: Whether the entry is transcript-only.
user_type: builtins.str | None: The userType recorded for the entry, e.g. external, or None when absent.
slug: builtins.str | None: The session slug recorded for the entry, or None when absent.

CcVersion

CcVersion=NewType("CcVersion", str)

Usage

Token usage and cache accounting for a single assistant turn or a -p (print mode) result.

Usage

Usage()

Exposes both the flat cache_creation_input_tokens and the per-TTL cache_creation split, faithfully and without opinion.

Attributes

input_tokens: builtins.int: The number of input tokens consumed by the turn.
output_tokens: builtins.int: The number of output tokens produced by the turn.
cache_read_input_tokens: builtins.int: The number of input tokens served from the cache.
cache_creation_input_tokens: builtins.int: The flat total of input tokens written to the cache.
cache_creation: CacheCreation | None: The per-TTL split of cache-creation tokens, when present.
service_tier: builtins.str | None: The service tier that billed the turn, when present.
inference_geo: builtins.str | None: The inference geography that served the turn, when present.
server_tool_use: ServerToolUse | None: Server-side tool invocation counts, when present.

ModelUsage

Per-model token usage and cost from a -p (print mode) result’s modelUsage map.

Usage

ModelUsage()

Attributes

input_tokens: builtins.int: The number of input tokens consumed by the model.
output_tokens: builtins.int: The number of output tokens produced by the model.
cache_read_input_tokens: builtins.int: The number of input tokens served from the cache.
cache_creation_input_tokens: builtins.int: The flat total of input tokens written to the cache.
web_search_requests: builtins.int: The number of server-side web-search requests billed to the model.
cost_usd: builtins.float: The cost in USD attributed to the model.
context_window: builtins.int: The model’s context window size in tokens.
max_output_tokens: builtins.int: The model’s maximum output token budget.

CacheCreation

The split of cache-creation input tokens by TTL bucket.

Usage

CacheCreation()

Attributes

ephemeral_5m_input_tokens: builtins.int: Cache-creation tokens written to the 5-minute TTL bucket.
ephemeral_1h_input_tokens: builtins.int: Cache-creation tokens written to the 1-hour TTL bucket.

ServerToolUse

Server-side tool invocation counts billed within a turn.

Usage

ServerToolUse()

Attributes

web_search_requests: builtins.int: The number of server-side web-search requests.
web_fetch_requests: builtins.int: The number of server-side web-fetch requests.

Attribution

The plugin, skill, or MCP tool an assistant turn is attributed to.

Usage

Attribution()

Present on an AssistantEvent only when the entry carries at least one of the four attribution fields; each component is independently optional.

Attributes

plugin: builtins.str | None: The plugin the turn is attributed to, or None.
skill: builtins.str | None: The skill the turn is attributed to, or None.
mcp_server: builtins.str | None: The MCP server the turn is attributed to, or None.
mcp_tool: builtins.str | None: The MCP tool the turn is attributed to, or None.

ApiError

The upstream API error an assistant turn failed with.

Usage

ApiError()

Present on an AssistantEvent only when the entry’s isApiErrorMessage flag is set; each component is independently optional.

Attributes

error: builtins.str | None: The error kind the API reported, e.g. rate_limit, or None.
status: builtins.int | None: The HTTP status of the failed request, e.g. 429, or None.
details: builtins.str | None: The free-text error detail, or None.

McpServer

An MCP server entry from the -p init element.

Usage

McpServer()

Attributes

name: builtins.str: The configured name of the MCP server.
status: builtins.str: The connection status reported for the server.

Plugin

A plugin entry from the -p init element.

Usage

Plugin()

Attributes

name: builtins.str: The plugin’s name.
path: builtins.str: The filesystem path the plugin was loaded from.
source: builtins.str: The source the plugin was installed from.

InitInfo

The session init snapshot from a -p system/init element.

Usage

InitInfo()

Attributes

mcp_servers: tuple[McpServer, …]: The MCP servers configured for the session.
plugins: tuple[Plugin, …]: The plugins loaded for the session.
tools: tuple[str, …]: The tool names available to the session.
skills: tuple[str, …]: The skill names available to the session.

tool_uses()

The event’s tool-use blocks, in content order.

Usage

Source

tool_uses(event)

thinking_chars()

The total character count of the event’s extended-thinking blocks.

Usage

Source

thinking_chars(event)

parse_event()

Parse one decoded transcript-line mapping into its typed event view.

Usage

Source

parse_event(data)

Serializes data and parses it through the native backend — the same path parse_events_from_bytes() uses — so the result is a lazy view over a single-entry parse. A structurally malformed line raises KeyError / ValueError (a missing type, a missing required field); an unmodeled type yields an ~cc_transcript.models.OtherEvent; a line the tolerant parser drops (a below-MINYEAR timestamp) reads as None.

parse_events()

Parse raw transcript-line mappings into typed native events.

Usage

Source

parse_events(*lines)

Serializes each mapping to a JSONL line and folds them through the native backend — the same path parse_events_from_bytes() and production use — so the result is a list of lazy views over a multi-line parse. Lines the tolerant parser drops (a below-MINYEAR timestamp) never materialize.

parse_events_from_bytes()

Parse a JSONL transcript byte buffer into typed native events.

Usage

Source

parse_events_from_bytes(raw)

Compositionality contract: parsing splits on newlines and folds each line independently, so for any split of raw on a line boundary, parse_events_from_bytes(prefix) + parse_events_from_bytes(suffix) equals parse_events_from_bytes(prefix + suffix) — value equality on the views’ structural __eq__. Each call owns its buffer; no state carries across calls. Blank, undecodable, and non-mapping lines are skipped identically wherever the split falls, and an unterminated final line parses the same as a terminated one. A line that fails typed parsing — a JSON object missing a required field — raises identically wherever the split falls: the side containing that line raises, so the equation above applies to inputs that parse. Splits inside a line are out of contract: a mid-line split is not a line boundary, and the fragments may parse differently than the whole line.

Incremental consumers — tail parsers re-parsing an appended slice cut on a newline boundary — may rely on this contract; it is pinned by the line-boundary sweep in tests/test_parser.py.

parse_print_result()

Parse a ‘claude -p –output-format json’ payload into a ~cc_transcript.models.PrintResult.

Usage

Source

parse_print_result(raw)

Parameters

raw: bytes: The raw bytes of the JSON array claude -p emits.

Returns

PrintResult: The parsed -p (print mode) result: billing, usage, structured output, init
snapshot, and the conversational messages.