# 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](docs/claude-jsonl-reference/01-format-specification.md) | Complete JSONL format spec with all fields |
| [02-message-types](docs/claude-jsonl-reference/02-message-types.md) | Every message type with concrete examples |
| [03-tool-lifecycle](docs/claude-jsonl-reference/03-tool-lifecycle.md) | Tool call flow from invocation to result |
| [04-subagent-teams](docs/claude-jsonl-reference/04-subagent-teams.md) | Subagent and team message formats |
| [05-edge-cases](docs/claude-jsonl-reference/05-edge-cases.md) | Error handling, malformed input, recovery |
| [06-quick-reference](docs/claude-jsonl-reference/06-quick-reference.md) | 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

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

## Testing

```bash
pytest tests/
```

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