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
This commit is contained in:
teernisse
175
README.md
Normal file
175
README.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user