Claude Transcript Anatomy

The Three Records People Confuse

There are three related but different surfaces: the persisted transcript file, the live stream emitted by CLI or SDK output modes, and the JSON payloads passed to hooks or status-line commands. They can describe the same run, but they are not interchangeable.

The persisted transcript is the durable artifact. Stream output is useful for automation, CI, and live processors. Hook and status-line payloads are lifecycle snapshots: they give enough context for a command to decide what to do at that moment.

Reading JSONL Without Overfitting

JSONL means one JSON object per line. That makes transcripts append-friendly and easy to stream, but it also tempts people to write fragile parsers that assume every line has exactly the same shape. A safer parser treats each line as an event-like record, branches by known fields, preserves unknown fields, and emits warnings rather than crashing on new versions.

If you are building a converter, keep the raw line number and source file path in derived output. That one choice makes later audits easier: a reviewer can jump from a friendly Markdown section back to the exact raw record.

• Parse with a JSONL reader, not split-based string matching.
• Preserve unknown fields for future Claude Code versions.
• Keep source filename, line number, session ID, timestamp if present, and parent/subagent relationships.

Hook Context Is A Lens, Not The Whole Run

Claude Code hook inputs include lifecycle context such as session ID, current working directory, and transcript path. For subagent events, Anthropic documents a separate subagent transcript path. That is enough to build audit hooks, but a hook payload is still a momentary input to the hook, not the complete transcript.

When a hook writes its own audit entry, include the hook event name and tool identifier, then store a pointer to the transcript rather than copying the entire transcript into every audit row.

Stream Output Has A Different Job

The CLI reference documents --output-format stream-json and related flags for print mode. That surface is ideal for scripts that need to consume messages as they happen. It is also where flags such as including hook events or partial messages become relevant.

Do not assume stream output and persisted transcripts are byte-for-byte mirrors. Treat stream output as an automation interface and the transcript as a persistence artifact. When exact provenance matters, store both the command invocation and the transcript pointer.