# Claude JSONL Session Log Reference

Comprehensive documentation for parsing and processing Claude Code JSONL session logs in the AMC project.

## Overview

Claude Code stores all conversations as JSONL (JSON Lines) files — one JSON object per line. This documentation provides authoritative specifications for:

- Message envelope structure and common fields
- All message types (user, assistant, progress, system, summary, etc.)
- Content block types (text, tool_use, tool_result, thinking)
- Tool call lifecycle and result handling
- Subagent spawn and team coordination formats
- Edge cases, error handling, and recovery patterns

## Documents

| Document | Purpose |
|----------|---------|
| [01-format-specification.md](./01-format-specification.md) | Complete JSONL format spec with all fields |
| [02-message-types.md](./02-message-types.md) | Every message type with concrete examples |
| [03-tool-lifecycle.md](./03-tool-lifecycle.md) | Tool call flow from invocation to result |
| [04-subagent-teams.md](./04-subagent-teams.md) | Subagent and team message formats |
| [05-edge-cases.md](./05-edge-cases.md) | Error handling, malformed input, recovery |
| [06-quick-reference.md](./06-quick-reference.md) | Cheat sheet for common operations |

## File Locations

| Content | Location |
|---------|----------|
| Claude sessions | `~/.claude/projects/<encoded-path>/<session-id>.jsonl` |
| Codex sessions | `~/.codex/sessions/**/<session-id>.jsonl` |
| Subagent transcripts | `~/.claude/projects/<path>/<session-id>/subagents/agent-<id>.jsonl` |
| AMC session state | `~/.local/share/amc/sessions/<session-id>.json` |
| AMC event logs | `~/.local/share/amc/events/<session-id>.jsonl` |

## Path Encoding

Project paths are encoded by replacing `/` with `-` and adding a leading dash:
- `/Users/taylor/projects/amc` → `-Users-taylor-projects-amc`

## Key Principles

1. **NDJSON format** — Each line is complete, parseable JSON
2. **Append-only** — Sessions are written incrementally
3. **UUID linking** — Messages link via `uuid` and `parentUuid`
4. **Graceful degradation** — Always handle missing/unknown fields
5. **Type safety** — Validate types before use (arrays vs strings, etc.)

## Sources

- [Claude Code Hooks Reference](https://code.claude.com/docs/en/hooks.md)
- [Claude Code Headless Documentation](https://code.claude.com/docs/en/headless.md)
- [Anthropic Messages API Reference](https://docs.anthropic.com/en/api/messages)
- [Inside Claude Code: Session File Format](https://medium.com/@databunny/inside-claude-code-the-session-file-format-and-how-to-inspect-it-b9998e66d56b)
- [Community: claude-code-log](https://github.com/daaain/claude-code-log)
- [Community: claude-JSONL-browser](https://github.com/withLinda/claude-JSONL-browser)