Claude Code JSONL format research

Architecture research that preceded cc-prism. Complete documentation of Claude Code’s session storage format—useful reference for anyone parsing .jsonl transcripts.

Claude Code Session Storage

Sessions stored at ~/.claude/projects/{mangled-path}/:

• Main sessions: {session-uuid}.jsonl
• Agent conversations: agent-{agent-id}.jsonl
• Each line = complete JSON object

Messages form a linked chain via UUID references:

• uuid — unique identifier
• parentUuid — parent message (null for root)
• sessionId — session identifier
• isSidechain — agent/sub-assistant flag

JSONL Message Type Catalog

1. User Messages (type: "user")

{
  "type": "user",
  "userType": "human",
  "message": { "role": "user", "content": "string or ContentItem[]" },
  "toolUseResult": { "agentId": "..." }  // Optional
}

Content can be: simple string, ContentItem array, or special formats (<command-name>, <local-command-stdout>).

2. Assistant Messages (type: "assistant")

{
  "type": "assistant",
  "message": {
    "content": [
      {"type": "text", "text": "..."},
      {"type": "thinking", "thinking": "..."},
      {"type": "tool_use", "name": "Bash", "input": {...}},
      {"type": "image", "source": {...}}
    ],
    "stop_reason": "end_turn" | "tool_use",
    "usage": { "input_tokens": 1234, "output_tokens": 567 }
  }
}

3. System Messages (type: "system")

Can have null content (skip) or warnings/notifications.

4. Summary Messages (type: "summary")

Auto-generated summaries referencing messages via leafUuid.

5. Queue Operation (type: "queue-operation")

Internal queueing. remove operations = user steering inputs.

6. File History Snapshot (type: "file-history-snapshot")

Internal backup metadata. Skip rendering.

Edge Cases Discovered

• Messages can have null content
• Tool results nested in toolUseResult with optional agentId
• Multiple rapid assistant messages = streaming updates
• context_management field appears during compaction
• Content can mix types: text + thinking + tool_use in same message

claude-code-log Reuse Analysis

Analyzed claude-code-log (537★) for reusable components:

Component	Reusability	Decision
Pydantic models	100%	Fork directly
Parser logic	90%	Reuse core, adapt I/O
Tool formatters	60%	Extract patterns
HTML templates	20%	Rebuild in React
CSS colors	0%	Use Tokyo Night instead

Tokyo Night Palette Reference

Background: #1a1b26    Foreground: #a9b1d6
Comment: #565f89       Selection: #33467C
Red: #f7768e           Green: #9ece6a
Yellow: #e0af68        Blue: #7aa2f7
Purple: #bb9af7        Cyan: #7dcfff
Orange: #ff9e64

Key Finding: Claude Code Uses React

Binary analysis of /home/gulp/.local/bin/claude:

• Contains react-jsx-parser, bun-framework-react strings
• Uses Ink framework for terminal rendering
• ANSI escape sequences generated from React component tree

Can’t extract components (compiled binary) — must reverse-engineer ANSI output or build from scratch.