781e74cda2
Create authoritative documentation suite for Claude Code JSONL session log processing, synthesized from codebase analysis, official Anthropic documentation, and community tooling research. Documentation structure (docs/claude-jsonl-reference/): 01-format-specification.md (214 lines): - Complete message envelope structure with all fields - Content block types (text, thinking, tool_use, tool_result) - Usage object for token reporting - Model identifiers and version history - Conversation DAG structure via parentUuid 02-message-types.md (346 lines): - Every message type with concrete JSON examples - User messages (string content vs array for tool results) - Assistant messages with all content block variants - Progress events (hooks, bash, MCP) - System, summary, and file-history-snapshot types - Codex format differences (response_item, function_call) 03-tool-lifecycle.md (341 lines): - Complete tool invocation to result flow - Hook input/output formats (PreToolUse, PostToolUse) - Parallel tool call handling - Tool-to-result pairing algorithm - Missing result edge cases - Codex tool format differences 04-subagent-teams.md (363 lines): - Task tool invocation and input fields - Subagent transcript locations and format - Team coordination (TeamCreate, SendMessage) - Hook events (SubagentStart, SubagentStop) - AMC spawn tracking with pending spawn registry - Worktree isolation for subagents 05-edge-cases.md (475 lines): - Parsing edge cases (invalid JSON, type ambiguity) - Type coercion gotchas (bool vs int in Python) - Session state edge cases (orphans, dead detection) - Tool call edge cases (missing results, parallel ordering) - Codex-specific quirks (content injection, buffering) - File system safety (path traversal, permissions) - Cache invalidation strategies 06-quick-reference.md (238 lines): - File locations cheat sheet - jq recipes for common queries - Python parsing snippets - Common gotchas table - Useful constants - Debugging commands Also adds CLAUDE.md at project root linking to documentation and providing project overview for agents working on AMC. Sources include Claude Code hooks.md, headless.md, Anthropic Messages API reference, and community tools (claude-code-log, claude-JSONL-browser). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
# 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)
|