# 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
```json
{
  "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)
```json
{
  "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
```json
{
  "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)
```json
{
  "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
```json
{
  "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)
```json
{
  "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
```json
{
  "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
```json
{
  "type": "progress",
  "data": {
    "type": "bash_progress",
    "status": "running",
    "toolName": "Bash",
    "command": "npm test"
  }
}
```

### MCP Progress
```json
{
  "type": "progress",
  "data": {
    "type": "mcp_progress",
    "server": "playwright",
    "tool": "browser_navigate",
    "status": "complete"
  }
}
```

## Type: `system`

System messages and metadata entries.

### Local Command
```json
{
  "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
```json
{
  "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.

```json
{
  "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.

```json
{
  "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)
```json
{
  "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)
```json
{
  "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)
```json
{
  "type": "response_item",
  "payload": {
    "type": "function_call",
    "call_id": "call_abc123",
    "name": "Grep",
    "arguments": "{\"pattern\": \"TODO\"}"
  }
}
```

### Reasoning (Thinking)
```json
{
  "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 |