Files

teernisse 781e74cda2 docs(jsonl): add comprehensive Claude JSONL session log reference

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>

2026-02-28 00:48:55 -05:00

2.8 KiB

Raw Blame History

AMC (Agent Management Console)

A dashboard and management system for monitoring and controlling Claude Code and Codex agent sessions.

Key Documentation

Claude JSONL Session Log Reference

Location: docs/claude-jsonl-reference/

Comprehensive documentation for parsing and processing Claude Code JSONL session logs. Always consult this before implementing JSONL parsing logic.

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

Architecture

Server (Python)

The server uses a mixin-based architecture in amc_server/:

Module	Purpose
`server.py`	Main AMC server class combining all mixins
`mixins/parsing.py`	JSONL reading and token extraction
`mixins/conversation.py`	Claude/Codex conversation parsing
`mixins/state.py`	Session state management
`mixins/discovery.py`	Codex session auto-discovery
`mixins/spawn.py`	Agent spawning via Zellij
`mixins/control.py`	Session control (focus, dismiss)
`mixins/skills.py`	Skill enumeration
`mixins/http.py`	HTTP routing

Dashboard (React)

Single-page app in dashboard/ served via HTTP.

File Locations

Content	Location
Claude sessions	`~/.claude/projects/<encoded-path>/<session-id>.jsonl`
Codex sessions	`~/.codex/sessions/**/<session-id>.jsonl`
AMC session state	`~/.local/share/amc/sessions/<session-id>.json`
AMC event logs	`~/.local/share/amc/events/<session-id>.jsonl`
Pending spawns	`~/.local/share/amc/pending_spawns/<spawn-id>.json`

Critical Parsing Notes

Content type ambiguity — User message content can be string (user input) OR array (tool results)
Missing fields — Always use .get() with defaults for optional fields
Boolean vs int — Python's isinstance(True, int) is True; check bool first
Partial reads — When seeking to file end, first line may be truncated
Codex differences — Uses response_item type, function_call for tools

Testing

pytest tests/

All parsing edge cases are covered in tests/test_parsing.py and tests/test_conversation.py.

2.8 KiB Raw Blame History