From c777ef05b67d02461514eb857b28d90357ba2e73 Mon Sep 17 00:00:00 2001 From: teernisse Date: Wed, 25 Feb 2026 11:21:35 -0500 Subject: [PATCH] docs: add comprehensive README with architecture and API reference 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 --- README.md | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1ec0ca7 --- /dev/null +++ b/README.md @@ -0,0 +1,175 @@ +# AMC — Agent Mission Control + +A real-time dashboard for monitoring and interacting with Claude Code sessions. + +## Overview + +AMC provides a unified view of all running Claude Code sessions across projects. It displays session status, conversation history, and pending questions — and allows you to respond directly from the dashboard without switching terminal tabs. + +## Features + +- **Real-time monitoring** — Sessions are grouped by status (needs attention, active, starting, done) with 3-second polling +- **Conversation history** — View the full chat history for any session, pulled from Claude Code's JSONL logs +- **Response injection** — Send responses to agents directly via Zellij pane integration +- **Question detection** — Detects both structured `AskUserQuestion` prompts and prose questions (messages ending with "?") +- **Session lifecycle** — Automatically cleans up orphaned sessions and stale event logs + +## Installation + +1. Clone this repository +2. Symlink the launcher to your PATH: + +```bash +ln -s /path/to/amc/bin/amc ~/.local/bin/amc +``` + +3. Configure Claude Code hooks (see [Hook Setup](#hook-setup)) + +## Usage + +```bash +amc start # Start the server and open the dashboard +amc stop # Stop the server +amc status # Check if the server is running +``` + +The dashboard opens at `http://127.0.0.1:7400`. + +## Hook Setup + +AMC requires Claude Code hooks to report session state. Add this to your `~/.claude/settings.json`: + +```json +{ + "hooks": { + "SessionStart": [ + { "command": "/path/to/amc/bin/amc-hook" } + ], + "UserPromptSubmit": [ + { "command": "/path/to/amc/bin/amc-hook" } + ], + "Stop": [ + { "command": "/path/to/amc/bin/amc-hook" } + ], + "SessionEnd": [ + { "command": "/path/to/amc/bin/amc-hook" } + ], + "PreToolUse": [ + { "matcher": "AskUserQuestion", "command": "/path/to/amc/bin/amc-hook" } + ], + "PostToolUse": [ + { "matcher": "AskUserQuestion", "command": "/path/to/amc/bin/amc-hook" } + ] + } +} +``` + +## Architecture + +``` +┌─────────────────────┐ ┌─────────────────────┐ +│ Claude Code │────▶│ amc-hook │ +│ (hooks) │ │ (writes state) │ +└─────────────────────┘ └──────────┬──────────┘ + │ + ▼ + ┌─────────────────────┐ + │ ~/.local/share/ │ + │ amc/sessions/ │ + │ amc/events/ │ + └──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ ┌─────────────────────┐ +│ Dashboard │◀────│ amc-server │ +│ (Preact UI) │ │ (Python HTTP) │ +└─────────────────────┘ └─────────────────────┘ +``` + +### Components + +| Component | Description | +|-----------|-------------| +| `bin/amc` | Launcher script — start/stop/status commands | +| `bin/amc-server` | Python HTTP server serving the API and dashboard | +| `bin/amc-hook` | Hook script called by Claude Code to write session state | +| `dashboard-preact.html` | Single-file Preact dashboard | + +### Data Storage + +All runtime data lives in `~/.local/share/amc/`: + +| Path | Contents | +|------|----------| +| `sessions/*.json` | Current session state (one file per session) | +| `events/*.jsonl` | Event log for each session (append-only) | +| `server.pid` | PID file for the running server | +| `server.log` | Server stdout/stderr | + +## API Reference + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/` | Dashboard HTML | +| GET | `/api/state` | All sessions as JSON | +| GET | `/api/events/{id}` | Event timeline for a session | +| GET | `/api/conversation/{id}?project_dir=...` | Conversation history (from Claude Code logs) | +| POST | `/api/dismiss/{id}` | Dismiss (delete) a completed session | +| POST | `/api/respond/{id}` | Send a response to a session | + +### Response Injection + +The `/api/respond/{id}` endpoint injects text into a session's Zellij pane. Request body: + +```json +{ + "text": "your response here", + "freeform": true, + "optionCount": 3 +} +``` + +- `text` — The response to send +- `freeform` — If true, treats as freeform text (selects "Other" option first) +- `optionCount` — Number of options in the current question (used for freeform) + +Response injection works via: +1. **Zellij plugin** (`~/.config/zellij/plugins/zellij-send-keys.wasm`) — Preferred, no focus change +2. **write-chars fallback** — Uses `zellij action write-chars`, changes focus + +## Session Statuses + +| Status | Meaning | +|--------|---------| +| `starting` | Session started, no prompt submitted yet | +| `active` | Session is processing work | +| `needs_attention` | Agent is waiting for user input (question or AskUserQuestion) | +| `done` | Session stopped (can be dismissed) | + +## Cleanup Behavior + +- **Orphan sessions**: Sessions with missing Zellij sessions in "starting" status are auto-deleted +- **Stale "starting" sessions**: Sessions stuck in "starting" for >1 hour are removed +- **Stale event logs**: Event logs without matching sessions are deleted after 24 hours +- **SessionEnd**: Deletes the session file immediately + +## Requirements + +- Python 3.8+ +- Zellij (for response injection) +- Claude Code with hooks support + +## Optional: Zellij Plugin + +For seamless response injection without focus changes, install the `zellij-send-keys` plugin: + +```bash +# Build and install the plugin +# (See zellij-send-keys repository for instructions) +``` + +Place the compiled WASM at `~/.config/zellij/plugins/zellij-send-keys.wasm`. + +## License + +MIT