Transcript Format
A transcript is a text file with one JSON object on each line.
Each object is a message, or a note about the session.
Claude Code appends a line as things happen. So a crash loses little.
The official docs say the format is internal and changes between versions. So a script that reads it can break.
Do not edit the file. For scripts, use /export or print mode output.
Where Files Live
Source: Explore the .claude Directory: Application Data.
~/.claude/history.jsonlevery prompt you typedprojects/<project>/<session>.jsonlthe transcript<session>.orphaned-<time>-<id>.jsonlset aside, not in the picker<session>.jsonl.superseded-<time>set aside, not in the picker<session>/subagents/one transcript per subagenttool-results/large tool outputs and MCP images
The <project> name is the folder path. In it, - replaces every character other than a letter or a digit.
CLAUDE_CONFIG_DIR moves ~/.claude. See Sessions and Storage for cleanup and resume rules.
How the Lines Link
Most lines carry uuid and parentUuid. The parentUuid field points to the line before. So the lines form a chain.
A branch or a rewind makes a second child for one parent. The last-prompt line holds a leafUuid that marks the tip the picker uses.
Common Fields
These keys appear on user, assistant, attachment, and system lines.
| Field | Status | Meaning |
|---|---|---|
type | Undocumented: Only the program shows this item. It can change without notice. | The line type (see the next section). |
uuid | Undocumented: Only the program shows this item. It can change without notice. | ID of the line. The same in the file and in every later read. |
parent | Undocumented: Only the program shows this item. It can change without notice. | uuid of the line before. null for the first line. |
session | Undocumented: Only the program shows this item. It can change without notice. | The session ID. Also written as session_ on some lines. |
timestamp | Undocumented: Only the program shows this item. It can change without notice. | When Claude Code wrote the line, in ISO form. |
cwd | Undocumented: Only the program shows this item. It can change without notice. | The working folder. |
git | Undocumented: Only the program shows this item. It can change without notice. | The git branch at the time, if any. |
version | Undocumented: Only the program shows this item. It can change without notice. | The Claude Code version that wrote the line. |
entrypoint | Undocumented: Only the program shows this item. It can change without notice. | The host that started the session, such as cli or sdk-. See Architecture. |
user | Undocumented: Only the program shows this item. It can change without notice. | The kind of user account. |
is | Undocumented: Only the program shows this item. It can change without notice. | true on lines that belong to a subagent branch. |
is | Undocumented: Only the program shows this item. It can change without notice. | true on a user-side row the person did not type, such as a reminder. |
Line Types
All rows are
type | Main keys | Meaning |
|---|---|---|
user | message, prompt, permission, permission, tool, source, origin, prompt, turn, turn, sandboxed | A user turn or a tool result. Since 2. a shell tool result can carry sandboxed, whether the command ran in the sandbox (the program, and probe print.). |
assistant | message, request, request, requested, effort, per, advisor, api | A reply of the model. |
system | subtype, content, level, duration, message | A note that the model never reads. |
attachment | attachment, rendered, rendered, rendered, rendered | Context that Claude Code adds beside the conversation. rendered is the text the model sees and rendered is user or system. rendered is true on a remote_ attachment, and rendered is on a queued_ attachment whose text differs inside a human turn (the program). |
queue- | operation, content, command, delivery, reason | A prompt or command that waits in the queue. |
api- | params, shape, cache, request, query, base, keep, tail, id | The shape of one request. |
api- | shape, shape | The system and tools of a request, stored once. |
api- | hash, message | A message stored by its hash. |
file- | message, snapshot, is | A file checkpoint for rewind. |
file- | message, snapshot, backup, tracking | A change to a checkpoint. |
last- | last, leaf | The last prompt, for the picker. |
ai- | ai | The title that the model made for the session. |
mode | mode | The mode of the session. Seen value: normal. |
permission- | permission | The permission mode. Seen value: auto. |
cost- | total, total, total, total, total, total, total, model, has, start | Totals for cost and time. Since 2., each model entry also has cache and cache (see Stream JSON Messages). |
atis- | atis | The atis value of the session's feature-flag client, Claude Code keeps it once per conversation, so it stays the same. Claude Code sends it as the x- header. Empty without a flag value (it was empty in our stub run). |
Lines of types file-history-snapshot, file-history-delta, last-prompt, ai-title, mode, permission-mode, cost-state, atis-latch, and queue-operation carry sessionId but not the chain fields.
Other Types in the Writer
These names are in the program next to the writer. The meanings come from the writer and reader code (source: the program), not from example lines.
type | Main keys | Meaning |
|---|---|---|
custom- | custom | The title you set, for example with /. |
agent-, agent- | The name and color of the session's agent. /, /, or an agent sets them. | |
agent- | The agent definition that the session runs as, for example from --. | |
tag | tag | A tag on the session. |
worktree- | worktree | The worktree that the session works in. null after it ends. |
pr- | pr, pr, pr, timestamp | Ties the session to a pull request. |
bridge- | bridge, last, session, owner ids | The Remote Control link. |
content- | replacements, agent | Records which large tool results a short stand-in replaced. A resume then uses the same stand-ins. |
attribution- | message | A snapshot of file-contribution data for commits. On load the program keeps only the last one and trims a large one. In 2. the program exports its writer function and no code calls it, so only older sessions hold these lines (the program). |
fork- | agent, parent, parent, context | A forked agent's pointer to its parent. The fork reads the parent's lines and does not copy them. |
observer- | observer, observer, agent, timestamp | An observer agent's pointer. |
progress | tool, parent, data | Progress of a running tool, hook, skill, or agent. data. is hook_, tool_, bash_, powershell_, agent_, agent_, skill_, search_, query_, workflow_, workflow_, workflow_, or artifact_. |
isolation- | side | Records a one-time choice about where the session runs, kept for resume. |
memory- | mode, after, reason, account | A stamp that auto memory switched mode. One per switch. |
dev- | folder | The folder of a mod under development that the session uses. |
frame- | path, frame, title, artifact | A link from the session to an artifact page. |
ended- | timestamp | Marks that the model ended the session. |
line- | bytes | Not a stored type. When a transcript is uploaded, {"type": replaces a line that could not be read or was too large. |
artifact- | artifacts, account, v | Bookkeeping for automatic replies to artifact comments. |
relocated | relocated | The working folder was moved. |
summary | leaf, summary | A summary line. The program reads these lines on load, and no code in 2. writes them, so only older sessions hold them. |
continued- | continued | Points to the session that continued this one. |
history-, artifact- | Also in the program's table. We read no further meaning. |
proactivity and language are not line types. They are kinds of attachment (attachment.type). proactivity carries status, level, and tools. language carries the reply language.
On resume the program applies a replay policy to each type. Unknown types add up.
- Last line wins: most types in the lists above, including
atis-latch. - Add up:
content-replacement,fork-context-ref,frame-link,artifact-comment-monitor, andmemory-mode. - Dropped at a compact boundary:
progress,file-history-snapshot,file-history-delta,last-prompt,continued-in,api-request-shape,api-request-blob, andapi-request.
The message Object
On user and assistant lines, message holds an API message.
| Field | Where | Meaning |
|---|---|---|
role | both | user or assistant. |
content | both | A string (a typed prompt), or an array of blocks. |
id, model, type | assistant | The API message ID, the model that answered, and message. |
stop_, stop_, stop_ | assistant | Why the model stopped. Seen values: tool_, end_. |
usage | assistant | Token counts (next table). |
container, context_, diagnostics, input_ | assistant | Extra fields of the API reply. |
Content block types seen: text, thinking, tool_use (in assistant lines), and text, tool_result (in user lines).
The usage Object
| Field | Meaning |
|---|---|
input_, output_ | Tokens read and written. |
cache_, cache_ | Tokens written to and read from the prompt cache. |
cache_ | A break-down of cache writes by lifetime. |
output_, iterations | More detail about output and about repeated passes. |
server_ | Counts of server-side tool calls. |
service_, speed, inference_ | The tier, the speed mode, and the region of the call. |
fallback_ | Present when a fallback model answered. |
user Line Fields
| Field | Meaning |
|---|---|
prompt | Groups the lines of one prompt. |
permission | The permission mode when the prompt was sent. |
permission | On a tool result: an object with decision (seen: accept), source (seen: config), and reason (seen: classifier, mode). |
tool | The structured result of a tool. Its keys depend on the tool. Seen for Bash: stdout, stderr, interrupted, is. Seen for edits: file, structured, original, user. Seen for Agent: agent, status, output, is. |
source | uuid of the assistant line whose tool_ this answers. |
origin | Who caused the line. Seen kinds: human, peer (a subagent hand-back). |
prompt | How the prompt came in. Seen: typed. |
turn, turn | Where the turn came from and its place in the chain. |
queue, queue | Set on queued prompts that skip those steps. |
assistant Line Fields
| Field | Meaning |
|---|---|
request | The request ID from the API. |
request | A reference to the matching api- line. |
requested | The model Claude Code asked for. The message. field shows the model that answered. |
effort, per | The effort level of the call. Since 2., effort is the level in force: if the conversation already holds an effort change that the model applied, the request uses that level, not a newly picked one. The program reads effort from output_ of the request it built (chunk- lines 135670 and 136924). In 2. it was built from the new pick (chunk- line 134537). |
advisor | The advisor model, if the advisor tool was on. |
api | The index of this block in the API reply. One reply can produce several lines. |
thinking, thinking | How Claude Code showed the thinking text, and how long it took. |
server, wire, wire | Internal fields about classifier calls and tool input on the wire. |
system Subtypes
subtype | Extra keys | Meaning |
|---|---|---|
turn_ | duration, message, pending | How long a turn took. |
local_ | content, level, command | The output of a local slash command. |
informational | content, level | A notice for the user. |
compact_ | (see Context and Compaction) | Marks where a compaction replaced the history. |
attachment Types
An attachment line holds an object in attachment with a type key.
Types seen in real 2.1.305 transcripts: total_tokens_reminder, output_style, output_style_instructions, queued_command, edited_text_file, skill_listing, agent_listing_delta, deferred_tools_delta, deferred_tools_record, mcp_instructions_delta, environment, date, model, session_context, instructions, auto_mode, credential_org, prompt_snapshot, silent_turn_reminder, nested_memory, and file. goal_status and remote_session_change were not seen there. A 2.1.305 stub run showed total_tokens_reminder, output_style, output_style_instructions, nested_memory, skill_listing, agent_listing_delta, deferred_tools_delta, environment, date, model, session_context, instructions, auto_mode, prompt_snapshot, and remote_session_change:
attachment.type | Meaning |
|---|---|
total_ | A reminder of the token budget. |
output_, output_ | The active output style. |
queued_ | A prompt that was queued while a turn ran. |
nested_ | A nested CLAUDE. that Claude Code loaded. |
skill_ | The list of skills. |
agent_, deferred_, mcp_ | Changes to agents, deferred tools, or MCP instructions. |
deferred_ | A record of deferred tools. |
edited_ | A note that a file changed outside the model. |
environment, date, model, session_, instructions | Environment and session facts. |
remote_ | The commit and pull request attribution text for git, as a reminder to the model. |
goal_, auto_, credential_, prompt_, silent_ | State of a goal, auto mode, the account, the prompt snapshot, and a reminder after a silent turn. |
The Mod API type SessionAppendMessage lists the name of an attachment as queued_command, nested_memory, and similar, and notice names such as compact_boundary and local_command.
queue-operation Values
The operation key was seen as enqueue, dequeue, and remove. A remove line carries reason.
File History Lines
A file-history-snapshot line holds snapshot with messageId, timestamp, and trackedFileBackups.
/rewind and --rewind-files use these to restore files. Claude Code keeps the newest 100 checkpoints.
api-request Lines
The params object of an api-request line has these keys: model, max_tokens, thinking, output_config, context_management, safeguards, and betas.
The system and tools parts are in a separate api-request-shape line with the same shapeHash.
Claude Code stores large messages once in api-request-blob lines. Lines refer to them by hash. See Request and Cache.
Example
Count the lines by type to see what a session holds:
jq -r .type ~/.claude/projects/<project>/<session>.jsonl | sort | uniq -c
List the tools the model called, in order:
jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") | .name' \
~/.claude/projects/<project>/<session>.jsonl
The file is plain text. A secret that a tool prints goes into it.
Set cleanupPeriodDays low, or CLAUDE_CODE_SKIP_PROMPT_HISTORY, if that matters to you.
Exact Fields
The exact fields are in this schema: https://clawdipedia.cc/schemas/claude-code-transcript.json, with one definition for each line type. The program builds this payload in code, not with a validator. So the schema comes from that code. A field marked x-unverified has a type that the code does not show. A field marked x-observed is a field that a probe saw.
It lists every field of this release. Build on the fields it names. Look each one up there before you rely on it.