amc/docs/claude-jsonl-reference/02-message-types.md

Claude JSONL Message Types

Complete reference for all message types in Claude Code session logs.

Type: user

User input messages (prompts, instructions, tool results).

Direct User Input

{
  "parentUuid": null,
  "isSidechain": false,
  "userType": "external",
  "cwd": "/Users/dev/myproject",
  "sessionId": "abc123-def456",
  "version": "2.1.20",
  "gitBranch": "main",
  "type": "user",
  "message": {
    "role": "user",
    "content": "Find all TODO comments in the codebase"
  },
  "uuid": "msg-001",
  "timestamp": "2026-02-27T10:00:00.000Z",
  "thinkingMetadata": {
    "maxThinkingTokens": 31999
  },
  "todos": [],
  "permissionMode": "bypassPermissions"
}

Tool Results (Following Tool Calls)

{
  "parentUuid": "msg-002",
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01ABC",
        "content": "src/api.py:45: # TODO: implement caching"
      },
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01DEF",
        "content": "src/utils.py:122: # TODO: add validation"
      }
    ]
  },
  "uuid": "msg-003",
  "timestamp": "2026-02-27T10:00:05.000Z"
}

Parsing Note: Check typeof content === 'string' vs Array.isArray(content) to distinguish user input from tool results.

Type: assistant

Claude's responses including text, thinking, and tool invocations.

Text Response

{
  "parentUuid": "msg-001",
  "type": "assistant",
  "message": {
    "role": "assistant",
    "type": "message",
    "model": "claude-opus-4-5-20251101",
    "id": "msg_bdrk_01Abc123",
    "content": [
      {
        "type": "text",
        "text": "I found 2 TODO comments in your codebase..."
      }
    ],
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 1500,
      "output_tokens": 200,
      "cache_read_input_tokens": 800
    }
  },
  "uuid": "msg-002",
  "timestamp": "2026-02-27T10:00:02.000Z"
}

With Thinking (Extended Thinking Mode)

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [
      {
        "type": "thinking",
        "thinking": "The user wants to find TODOs. I should use Grep to search for TODO patterns across all file types.",
        "signature": "eyJhbGciOiJSUzI1NiJ9..."
      },
      {
        "type": "text",
        "text": "I'll search for TODO comments in your codebase."
      }
    ]
  }
}

With Tool Calls

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_01Grep123",
        "name": "Grep",
        "input": {
          "pattern": "TODO",
          "output_mode": "content"
        }
      }
    ],
    "stop_reason": null
  }
}

Multiple Tool Calls (Parallel)

{
  "type": "assistant",
  "message": {
    "content": [
      {
        "type": "text",
        "text": "I'll search for both TODOs and FIXMEs."
      },
      {
        "type": "tool_use",
        "id": "toolu_01A",
        "name": "Grep",
        "input": {"pattern": "TODO"}
      },
      {
        "type": "tool_use",
        "id": "toolu_01B",
        "name": "Grep",
        "input": {"pattern": "FIXME"}
      }
    ]
  }
}

Type: progress

Progress events for hooks, tools, and async operations.

Hook Progress

{
  "parentUuid": "msg-002",
  "isSidechain": false,
  "type": "progress",
  "data": {
    "type": "hook_progress",
    "hookEvent": "PostToolUse",
    "hookName": "PostToolUse:Grep",
    "command": "node scripts/log-tool-use.js"
  },
  "parentToolUseID": "toolu_01Grep123",
  "toolUseID": "toolu_01Grep123",
  "timestamp": "2026-02-27T10:00:03.000Z",
  "uuid": "prog-001"
}

Bash Progress

{
  "type": "progress",
  "data": {
    "type": "bash_progress",
    "status": "running",
    "toolName": "Bash",
    "command": "npm test"
  }
}

MCP Progress

{
  "type": "progress",
  "data": {
    "type": "mcp_progress",
    "server": "playwright",
    "tool": "browser_navigate",
    "status": "complete"
  }
}

Type: system

System messages and metadata entries.

Local Command

{
  "parentUuid": "msg-001",
  "type": "system",
  "subtype": "local_command",
  "content": "<command-name>/usage</command-name>\n<command-args></command-args>",
  "level": "info",
  "timestamp": "2026-02-27T10:00:00.500Z",
  "uuid": "sys-001",
  "isMeta": false
}

Turn Duration

{
  "type": "system",
  "subtype": "turn_duration",
  "slug": "project-session",
  "durationMs": 65432,
  "uuid": "sys-002",
  "timestamp": "2026-02-27T10:01:05.000Z"
}

Type: summary

End-of-session or context compression summaries.

{
  "type": "summary",
  "summary": "Searched codebase for TODO comments, found 15 instances across 8 files. Prioritized by module.",
  "leafUuid": "msg-010"
}

Note: leafUuid points to the last message included in this summary.

Type: file-history-snapshot

File state tracking for undo/restore operations.

{
  "type": "file-history-snapshot",
  "messageId": "snap-001",
  "snapshot": {
    "messageId": "snap-001",
    "trackedFileBackups": {
      "/src/api.ts": {
        "path": "/src/api.ts",
        "originalContent": "...",
        "backupPath": "~/.claude/backups/..."
      }
    },
    "timestamp": "2026-02-27T10:00:00.000Z"
  },
  "isSnapshotUpdate": false
}

Codex Format (Alternative Agent)

Codex uses a different JSONL structure.

Session Metadata (First Line)

{
  "type": "session_meta",
  "timestamp": "2026-02-27T10:00:00.000Z",
  "payload": {
    "cwd": "/Users/dev/myproject",
    "timestamp": "2026-02-27T10:00:00.000Z"
  }
}

Response Item (Messages)

{
  "type": "response_item",
  "timestamp": "2026-02-27T10:00:05.000Z",
  "payload": {
    "type": "message",
    "role": "assistant",
    "content": [
      {"text": "I found the issue..."}
    ]
  }
}

Function Call (Tool Use)

{
  "type": "response_item",
  "payload": {
    "type": "function_call",
    "call_id": "call_abc123",
    "name": "Grep",
    "arguments": "{\"pattern\": \"TODO\"}"
  }
}

Reasoning (Thinking)

{
  "type": "response_item",
  "payload": {
    "type": "reasoning",
    "summary": [
      {"type": "summary_text", "text": "Analyzing the error..."}
    ]
  }
}

Message Type Summary

Type	Frequency	Content
user	Per prompt	User input or tool results
assistant	Per response	Text, thinking, tool calls
progress	Per hook/tool	Execution status
system	Occasional	Commands, metadata
summary	Session end	Conversation summary
file-history-snapshot	Start/end	File state tracking