Document AMC (Agent Mission Control) for new users and contributors:
- Overview: real-time dashboard for Claude Code session monitoring
- Features: session grouping, conversation history, response injection,
question detection (AskUserQuestion and prose), session lifecycle
- Installation: symlink setup and PATH configuration
- Hook Setup: complete settings.json configuration for all required
Claude Code hooks (SessionStart, UserPromptSubmit, Stop, SessionEnd,
PreToolUse/PostToolUse for AskUserQuestion)
- Architecture: ASCII diagram showing data flow from Claude Code hooks
through amc-hook to disk storage to amc-server to dashboard
- Components: descriptions of amc launcher, amc-server, amc-hook,
and dashboard-preact.html
- Data Storage: runtime data paths in ~/.local/share/amc/
- API Reference: all 6 endpoints with methods and descriptions
- Response Injection: request body format and two-phase freeform flow
- Session Statuses: starting, active, needs_attention, done
- Cleanup Behavior: orphan detection, stale session removal, event log gc
- Requirements: Python 3.8+, Zellij, Claude Code hooks
- Optional Zellij Plugin: for focus-free response injection
bin/amc:
- Add cross-platform browser opening: try 'open' (macOS) first,
fall back to 'xdg-open' (Linux) for desktop environments
- Wrap browser opening in conditional to avoid errors on headless systems
bin/amc-hook:
- Fix edge case in question extraction where tool_input.get("questions")
could return None instead of empty list, causing TypeError
Extend AMC to monitor Codex sessions alongside Claude Code:
Codex Integration:
- Discover active Codex sessions from ~/.codex/sessions/*.jsonl
- Parse Codex JSONL format (response_item/message payloads) for
conversation history, filtering out developer role injections
- Extract session metadata (cwd, timestamp) from session_meta records
- Match Codex sessions to Zellij panes via cwd for response injection
- Add ?agent=codex query param to /api/conversation endpoint
Session Lifecycle Improvements:
- Cache Zellij session list for 5 seconds to reduce subprocess calls
- Proactive liveness check: auto-delete orphan "starting" sessions
when their Zellij session no longer exists
- Clean up stale "starting" sessions after 1 hour (likely orphaned)
- Preserve existing event log cleanup (24h for orphan logs)
Code Quality:
- Refactor _serve_conversation into _parse_claude_conversation and
_parse_codex_conversation for cleaner separation
- Add _discover_active_codex_sessions for session file generation
- Add _get_codex_zellij_panes to match sessions to panes
- Use JSON error responses consistently via _json_error helper
Replace vanilla JS dashboard with a modern Preact-based implementation:
- Component architecture: Header, SessionCard, SessionGroup, Modal,
ChatMessages, QuestionBlock, SimpleInput, OptionButton, EmptyState
- Status-grouped display: sessions organized by needs_attention, active,
starting, and done with color-coded visual indicators
- Real-time conversation view: fetch and display chat history from
Claude Code JSONL logs with auto-scroll on new messages
- Inline response input: send messages directly from cards without
opening modal, supports both structured options and freeform text
- Modal detail view: full conversation with markdown rendering,
timestamps, and keyboard navigation (Enter to send, Escape to close)
- Smart polling: 3-second state refresh with silent conversation
updates for active sessions to minimize UI flicker
- Flexoki color scheme: custom dark theme with attention (amber),
active (green), starting (blue), and done (purple) status colors
- Berkeley Mono font stack with graceful fallbacks
- Tailwind CSS via CDN with custom color configuration
- Responsive card layout with fixed 600px height and overflow handling
The dashboard provides a unified view for monitoring multiple Claude
Code sessions, detecting when agents need human input, and responding
directly via Zellij pane injection.
