tomtomsatnav / agent-orchestration-standard

# AOS Dashboard
**A read-only live monitor for Claude Code.** It shows what your sessions and subagents are doing (agents, tasks, tokens, cost, file conflicts, alerts) as a streaming graph in the browser, a terminal view (`aos-dash`), an MCP server and a status line. It never starts, stops or steers agents. Local-only, zero dependencies.
Looking for orchestration (planning goals, launching and managing workers)? That is a different, separate and **experimental** project: aos-orchestrator, opt-in. This dashboard can display its goals, nothing more.
| Which piece do I want? | Repo | What it is |
|---|---|---|
| Watch my Claude Code agents live | this repo (dashboard) | Read-only monitor. Start here. |
| A standard for observable agent state | aos-1-spec | Open spec: heartbeat, plain-file state, event log. |
| Have agents planned and run for me | aos-orchestrator | Experimental engine that launches real `claude` workers. |
 The live dashboard on a synthetic demo dataset. More screenshots . 
## Install the dashboard
Needs Node 18+ and the Claude Code CLI. No dependencies to install.
 [code] 
Then start a new Claude Code session and open http://127.0.0.1:4318. The graph's `Streams` button (or `Q`) cycles Full / Quiet / Lines; Lines draws no particles and stops per-frame redraws, for the lowest overhead (measured). Local-only, read-only; hooks never log prompts, file contents or tool output, but do log event and tool names, working-folder and edited-file paths, transcript paths and a redacted short task description (full list: plugin/README.md). Status: personal project, macOS-first. MIT License.
**Lowest overhead:** run `aos-dash` for the terminal view (no browser tab, no animation), and set the graph's `Streams` button to `Lines`.
## GOALS panel
The GOALS panel only displays goals from the separate, experimental orchestrator, read from disk, but approving, pausing and starting goals needs the control server from aos-orchestrator (`aos-orch serve`, port 4319). Without it the panel is read-only. The files the dashboard reads are described in docs/orch-state-contract.md.
## Docs
- aos-1-spec: normative specification, schemas, conformance validator, reference runner
- aos-orchestrator: orchestrator engine and its design doc
- docs/dashboard.md: the Claude Code dashboard, highlights, debugging, security and threat model
- docs/architecture.md: how events flow from hooks to the UI
- docs/screenshots.md: screenshot gallery
- docs/overhead.md: measured monitor CPU and memory
- docs/orch-state-contract.md: the on-disk layout the dashboard reads from an orchestrator
- plugin/README.md: plugin details and the exact privacy field list
## Contributing
Issues and small pull requests are welcome. Edit the sources in the repo root (`monitor.mjs`, `hooks/`, `ui/`, `cli/`), then run `make build` and `make test`; keep it zero-dependency and Node 18 compatible.