Deep Technical Architecture & Guide

Under the Hood of AI Coding Agents: Decoding transcript.jsonl & Mastering Built-In Session Resumption

When your autonomous AI terminal agent refactors 15 files, executes 25 bash commands, and runs test suites—how does it persist that execution trajectory? Here is a complete architectural analysis of transcript.jsonl, event schemas, prompt cache economics, and every native CLI option to view and resume sessions.

1. Why JSONL? The Architecture Behind Append-Only Transcripts

Developers often ask: Why did Anthropic and OpenAI choose JSON Lines (JSONL) instead of a single history.json or an embedded SQLite database for terminal session logging?

The decision reflects core constraints in building streaming agentic runtimes:

• O(1) Append-Only Performance: As an LLM streams tokens via Server-Sent Events (SSE), appending a new JSON line to disk takes constant time. If transcripts used a standard JSON array ([{...}]), saving turn 100 would require parsing, re-serializing, and writing several megabytes of history on every tool execution.
• The Crash-Resilience Guarantee: Terminal agents regularly run heavy compilation loops, Docker commands, and unit tests. If a process hits an Out-Of-Memory (OOM) panic, receives a SIGINT (Ctrl+C), or your laptop battery dies, a monolithic JSON file gets permanently corrupted by an unclosed bracket. In JSONL, every prior line is already valid JSON.
• Streamable Memory-Efficient Parsing: Parsing a 50MB transcript does not require loading 50MB of heap memory. Stream processors (like Unix readline or Web Workers) inspect events line-by-line with $O(1)$ memory consumption.

2. Dissecting the JSONL Event Schema

Each line in a Claude Code or Codex transcript represents an atomic turn in the execution cycle. Below are the key event types you encounter:

A. The Developer's Prompt (USER_INPUT)

{
  "step_index": 1,
  "source": "USER_EXPLICIT",
  "type": "USER_INPUT",
  "status": "DONE",
  "timestamp": "2026-10-03T14:22:10.450Z",
  "content": "Add idempotent webhook retry logic to payment_service.go with exponential backoff."
}

B. The Model Reasoning & Tool Invocations (PLANNER_RESPONSE)

{
  "step_index": 2,
  "source": "MODEL",
  "type": "PLANNER_RESPONSE",
  "status": "DONE",
  "content": "I need to inspect payment_service.go to locate WebhookHandler and check database transactions.",
  "tool_calls": [
    {
      "name": "run_command",
      "args": {
        "CommandLine": "grep -n 'func WebhookHandler' payment_service.go"
      }
    }
  ],
  "usage": {
    "input_tokens": 1420,
    "cache_read_input_tokens": 1280,
    "output_tokens": 86
  }
}

C. Tool Outputs (TOOL_RESULT)

{
  "step_index": 3,
  "source": "SYSTEM",
  "type": "TOOL_RESULT",
  "status": "DONE",
  "content": "42:func WebhookHandler(w http.ResponseWriter, r *http.Request) {\n",
  "exit_code": 0
}

3. Native CLI Commands: Viewing & Resuming Sessions

Both Claude Code and OpenAI Codex provide built-in command-line options to list, inspect, and resume previous sessions:

Command	Shorthand	Execution Mechanics
claude --resume	claude -r	Launches an interactive terminal UI (TUI) listing previous sessions in the current directory.
claude --resume <id>	claude -r <id>	Immediately mounts and rehydrates the specific session matching <id>.
claude --continue	claude -c	Headless resume: continues the latest session in the current folder without displaying a picker.
codex resume	—	Scans ~/.codex/sessions/ and launches the interactive Codex session picker.
codex list	—	Prints a summary table of recent session IDs, token totals, and execution durations.

Where Transcripts Live on Disk

• Claude Code (macOS & Linux): ~/.claude/projects/<sanitized-repo-path>/transcript.jsonl
• Claude Code (Windows): %USERPROFILE%\.claude\projects\<sanitized-repo-path>\transcript.jsonl
• OpenAI Codex: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl and ~/.codex/memories.sqlite
• VS Code Copilot: ~/Library/Application Support/Code/User/workspaceStorage/<hash>/chatEditingSessions/

4. Power-User Terminal Recipes: Querying JSONL with jq

Because JSONL consists of individual line-delimited records, you can audit your agent's activity with fast shell one-liners:

Extract All Prompts in Chronological Order

jq -r 'select(.type=="USER_INPUT") | "\(.timestamp) ❯ \(.content)"' transcript.jsonl

Audit Every Bash Command Run by the AI

jq -r 'select(.type=="PLANNER_RESPONSE") | .tool_calls[]? | select(.name=="run_command") | .args.CommandLine' transcript.jsonl

Calculate Prompt Cache Hit Ratio

jq -s '
  map(.usage // empty) | {
    total_input: map(.input_tokens // 0) | add,
    cache_read: map(.cache_read_input_tokens // 0) | add,
    hit_rate: ((map(.cache_read_input_tokens // 0) | add) / (map(.input_tokens // 0) | add) * 100 | round)
  }
' transcript.jsonl

5. Beyond the CLI: Global Search with L2Cache

While claude -r is invaluable inside a single repository, software engineers frequently work across multiple microservices, repositories, and documentation trees in a single afternoon.

The native CLI tools cannot search across repositories or perform full-text searches inside past tool outputs. L2Cache for Mac indexes every transcript.jsonl and rollout-*.jsonl into an embedded, high-performance SQLite FTS5 index:

• Global Hotkey (⌥ Space): Search any prompt, regex, shell command, or model output across all projects simultaneously.
• 1-Click Terminal Resume: Launch your terminal directly into the matching directory with the session rehydrated.
• 100% On-Device Privacy: No indexing telemetry or prompt data is ever sent to external cloud servers.