Content
# DISPATCH
<p align="center">
<a href="https://github.com/thepixelabs/dispatch/actions/workflows/ci.yml"><img src="https://github.com/thepixelabs/dispatch/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/thepixelabs/dispatch/releases"><img src="https://img.shields.io/github/v/release/thepixelabs/dispatch?style=flat-square&labelColor=13161e&color=6366f1" alt="Release"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/thepixelabs/dispatch?style=flat-square&labelColor=13161e&color=4ade80" alt="License"></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-22c55e?style=flat-square&labelColor=13161e&logo=node.js&logoColor=22c55e" alt="Node"></a>
<img src="https://img.shields.io/badge/works%20with-Claude%20%C2%B7%20Gemini%20%C2%B7%20Copilot%20%C2%B7%20Codex-6366f1?style=flat-square&labelColor=13161e" alt="Works with Claude · Gemini · Copilot · Codex">
</p>
<p align="center">
<strong>A zero-config browser dashboard for your AI coding agent fleet — live status, phase progress, and what got left behind, all in one place.</strong>
</p>
<p align="center">
<img src="docs/assets/screenshots/dashboard.png" alt="Dispatch dashboard showing live agents, epic grid, and activity feed" width="900">
</p>
> No screenshot yet? Drop `dashboard.png` in `docs/assets/screenshots/` — see [that folder's README](docs/assets/screenshots/README.md) for the recommended capture settings.
---
## The problem
You have multiple AI coding agents running across terminals, coordinating through a shared `.tasks/` directory. Tracking what's happening means `cat`-ing plan files and grepping through logs — and you only find out an agent stalled after the fact. Dispatch watches `.tasks/` and shows everything live in a browser.
## Who this is for
Dispatch is for anyone running AI coding agents — whether that is two Claude Code agents in two terminals, a Gemini CLI crew, or a mixed fleet of Claude, Copilot, Gemini, and Codex agents splitting a large epic. If your agents write to `.tasks/`, Dispatch works without any setup.
Everything else is stable. If you hit a bug, [open an issue](https://github.com/thepixelabs/dispatch/issues) — we respond fast.
## Recovering incomplete work
Agents crash, run out of context, and stop mid-epic. When that happens, the phase they were working stays `IN_PROGRESS` forever — nobody finishes it, the epic stalls, and you only notice days later when you wonder why that feature never shipped.
The **Orders view** (formerly "Tasks view") exists specifically for this. It flattens every phase from every epic into one list. Phases whose agent is no longer alive are shown at the top, sorted by what is claimable now. You see the abandoned work immediately, click into the phase to read the execution log the previous agent left behind, and hand the phase to a fresh agent. The epic continues from exactly where the last agent stopped.
This is the feature that separates Dispatch from running `watch cat plan.md` in a terminal.
## What you get
- **See what got left behind** — the Orders view lists every unfinished phase across all epics, sorted by what is claimable now; recover stalled epics without losing any work the previous agent completed
- **Multi-provider agent support** — unified agent management across Claude Code, GitHub Copilot CLI, Gemini CLI, and OpenAI Codex; all agents appear in a single sidebar with provider badges; auto-discovery imports agents from any installed CLI at startup
- **Liveness at a glance** — status dots show every agent's live state; a stalled or crashed terminal turns red within seconds
- **Phase progress without opening files** — railroad tracks show exactly where each workstream stands across every registered project
- **Real-time activity feed** — streams phase summaries as agents finish; click any entry to read the full execution log and handoff notes
- **Cross-provider session tracking** — monitor active sessions and token usage across Claude, Copilot, Gemini, and Codex from a single dashboard; the provider filter persists in the URL
- **MCP shared state** — 11 tools exposed over HTTP/JSON-RPC 2.0; one-click install connects Claude Code, Gemini CLI, GitHub Copilot CLI, and OpenAI Codex CLI simultaneously. Every provider calls the same tools, reads the same state. See [MCP Provider Guides](docs/providers/README.md).
- **Agent graph view** — open the Agent Team modal to see your fleet as a tiered, physics-laid-out graph: glass-ringed nodes per agent, role-colored sectors, a breathing halo on live agents, and a top-right cost+task pill (green under $1, amber under $5, red at $5 and up). A draggable legend, a click-to-recenter mini-map, a zoom toolbar with Focus, and an optional idle-drift rotation give the screen a calm rhythm when the fleet is quiet. On mobile the graph collapses to a card list with relationship badges. See [Features — Agent graph view](docs/FEATURES.md#agent-graph-view) for the full visual encoding
- **Watch multiple projects at once** — register any number of repos; Dispatch watches them all simultaneously
- **LAN and iPad access** — open the dashboard from any device on your Wi-Fi network; LAN devices are read-only by design
- **Zero config** — if your agents already write to a `.tasks/` directory, Dispatch works out of the box
- **Agent RPG system** — an optional fun layer that gives each agent a class, stats, and a progression track tied to actual output (see below)
For the complete feature catalog, see [Features](docs/FEATURES.md).
## Tray app
Dispatch lives in your menu bar. Launch it once and forget it — the server keeps running in the background whether the window is open or not. Click the tray icon to reopen the dashboard at any time.
The tray menu shows the current agent count, the active port, and quick actions: Open Dashboard, Settings, and Quit. When agents are active, Quit asks for confirmation so you never accidentally disconnect a running fleet.
For a full walkthrough of window-close behavior, launch-at-login, and the quit confirmation, see [Tray App Guide](docs/TRAY_APP.md).
## LAN and iPad access
Run Dispatch on your Mac and open the dashboard on your iPad or phone over Wi-Fi. Enable LAN mode in Settings — Server, tap "Show QR Code", and scan from any device on the same network. LAN devices get a read-only view: they can watch agent activity but cannot spawn agents or change settings.
See [LAN Access Guide](docs/LAN_ACCESS.md) for the setup flow and network requirements.
## Install
### Option 1 — Homebrew (recommended)
```bash
brew install --cask thepixelabs/tap/dispatch
```
This installs the Dispatch tray app. Open it from your Applications folder or Spotlight. The menu bar icon appears immediately — no terminal required.
For updating, uninstalling, and troubleshooting the Homebrew install, see [docs/INSTALL_HOMEBREW.md](docs/INSTALL_HOMEBREW.md).
### Option 2 — Download the DMG
Download the latest `.dmg` from the [Releases page](https://github.com/thepixelabs/dispatch/releases), open it, and drag Dispatch to Applications.
### Option 3 — Run from source (contributors)
```bash
git clone https://github.com/thepixelabs/dispatch.git
cd dispatch
npm install
npm run dev
# Dashboard: http://localhost:5173
```
This path is for contributors and people who want to run the latest unreleased code. For day-to-day use, install via Homebrew or the DMG.
---
## Getting started
> **The Dispatch server must be running before you use the CLI.**
> - Tray app install (Homebrew / DMG): launch Dispatch from Applications or Spotlight — the server starts automatically.
> - Source install: run `npm run dev` in the repo root first.
>
> The `dispatch add` command talks to the local server over HTTP. If the server is not running you will see `ECONNREFUSED` and the command will exit immediately.
**1. Register a project to watch:**
```bash
dispatch add /path/to/your/project --name "My Project"
```
The project appears in the dashboard immediately. If you have existing `.tasks/` epics they load on the first watch cycle.
**2. Start an agent — two ways:**
**Option A — launch from your terminal (observer mode):**
```bash
cd /path/to/your/project
claude --agent ceo
```
The agent appears live in the dashboard — dispatch detects it via the JSONL session file your CLI writes automatically. Open more terminals, start more agents, watch them work. This path is preserved for power users who prefer their own terminal; see [ADR-022](docs/decisions/ADR-022-spawn-model-hybrid.md) for the spawn-model decision.
> **Attended vs autonomous.** Sessions launched from your terminal are *attended* — the user is watching. Orchestrator agents in attended sessions spawn subagents via the inline `Agent` tool, not `dispatch_spawn_agent`, so output streams live to the same terminal. Sessions launched by dispatch itself (Option B below, or via `dispatch_spawn_agent`) are *autonomous* — the dashboard owns the PTY. The MCP server rejects `dispatch_spawn_agent` from attended sessions with a `ModeViolation` error. Full mechanic: [`shared/protocol/blackboard.ts`](shared/protocol/blackboard.ts).
**Option B — spawn from the dashboard (orchestrator mode, default for new users):**
Click **+ New Run** in the dashboard, pick a persona, type a prompt, hit spawn. The dashboard launches the CLI as a subprocess and opens the chat surface for you. Equivalent over HTTP:
```bash
curl -X POST http://localhost:4242/api/runs \
-H "Content-Type: application/json" \
-d '{"persona":"ceo","prompt":"start the architecture review","cwd":"/path/to/your/project"}'
# Response: {"runId":"<uuid>"}
```
The `vendor` field is optional and defaults to Claude. Cancel and resume verbs are available at `POST /api/runs/:runId/cancel` and `POST /api/runs/:runId/resume`. Auth is delegated to the vendor CLI's existing login state — dispatch never reads `ANTHROPIC_API_KEY` itself; see [ADR-024](docs/decisions/ADR-024-auth-delegate-to-vendor-cli.md).
**3. Try the sample project (optional):**
Want to see the dashboard with realistic data before setting up a real project? Register the included sample project:
```bash
dispatch add /path/to/dispatch/sample-project --name "Sample Project"
```
It ships with two epics, phases in various states (DONE, IN_PROGRESS, BLOCKED), and execution log entries — so the dashboard looks alive immediately. See [`sample-project/README.md`](sample-project/README.md) for details.
## MCP Integration
**Full guide: [MCP.md](MCP.md)** — token generation, shell setup, install, verify, rotate, uninstall, troubleshooting.
Install Dispatch's MCP server in any AI coding agent you already use. Run the command for your provider once — the connection persists across sessions.
```bash
# Claude Code
claude mcp add --transport http --scope user dispatch http://127.0.0.1:4242/mcp --header "Authorization: Bearer $DISPATCH_MCP_TOKEN"
# Gemini CLI
gemini mcp add --transport http --scope user --trust -H "Authorization: Bearer $DISPATCH_MCP_TOKEN" dispatch http://127.0.0.1:4242/mcp
# OpenAI Codex CLI
codex mcp add dispatch --url http://127.0.0.1:4242/mcp --bearer-token-env-var DISPATCH_MCP_TOKEN
# GitHub Copilot CLI
copilot mcp add --transport http dispatch http://127.0.0.1:4242/mcp --header "Authorization: Bearer $DISPATCH_MCP_TOKEN" --tools "*"
```
`DISPATCH_MCP_TOKEN` is displayed in **Settings → Server** when Dispatch is running, or generate your own with `openssl rand -hex 32` and add it to `~/.zshrc`. Replace `4242` with your `DISPATCH_PORT` if you changed it. See [MCP.md § Persist the token](MCP.md#2-persist-the-token) for the full reasoning.
**Prefer a wrapper?** The `dispatch mcp` subcommand reads your running server's port and token automatically:
```bash
dispatch mcp install --all # install for all detected providers
dispatch mcp status # show install state per provider
dispatch mcp snippet --provider gemini # print the command without running it
```
**No terminal?** Open `http://localhost:4242`, go to **Settings → Server → Expose to External Tools**, and click **Install** next to your provider.
**Advanced / CI:** The HTTP API accepts `{"clients": ["all"]}` at `POST /api/integrations/mcp/install`. See [MCP Provider Guides](docs/providers/README.md) for the full API reference.
Full per-provider guides with troubleshooting: [docs/providers/README.md](docs/providers/README.md) | [Quick Start](docs/providers/quick-start.md)
---
## Rover companion
[Rover](https://github.com/thepixelabs/rover) is an SSH-friendly TUI session manager for your Mac, designed to live alongside Dispatch. Install:
brew install thepixelabs/tap/rover
# or
pipx install rover-tui
Landing page: https://rover.pixelabs.net
## Documentation
The full documentation lives on the [Dispatch docs site](https://thepixelabs.github.io/dispatch/):
| Document | Contents |
|----------|----------|
| [Quickstart](docs/QUICKSTART.md) | Install, first launch, Claude plugin setup |
| [Tray App Guide](docs/TRAY_APP.md) | Menu bar behavior, window-close, quit confirmation, launch at login |
| [LAN Access Guide](docs/LAN_ACCESS.md) | iPad/phone access, QR code flow, network requirements |
| [Feature Catalog](docs/FEATURES.md) | All features by category — includes multi-provider support, MCP server tools, provider setup, cost tracking per provider |
| [How It Works](https://thepixelabs.github.io/dispatch/docs/how-it-works/) | The `.tasks/` convention, multi-provider session tracking, MCP server, data flow |
| [CLI Guide](https://thepixelabs.github.io/dispatch/docs/cli-guide/) | Project management, multi-CLI agent setup, dashboard spawn |
| [Integrations](https://thepixelabs.github.io/dispatch/docs/integrations/mcp-overview/) | MCP tools, per-provider setup (Claude, Codex, Copilot, Gemini) |
| [MCP Integration (canonical)](MCP.md) | Token setup, install in any provider, verify, rotate, uninstall, troubleshooting |
| [MCP Provider Guides](docs/providers/README.md) | Per-provider MCP install guides: [Claude Code](docs/providers/claude-code.md), [Gemini](docs/providers/gemini.md), [Copilot](docs/providers/copilot.md), [Codex](docs/providers/codex.md) |
| [Blackboard Protocol](shared/protocol/blackboard.ts) | Canonical source — orchestrator/subagent split, plan.md write-first pattern, attended-vs-autonomous spawn primitive |
| [Agent Execution](https://thepixelabs.github.io/dispatch/docs/integrations/agent-execution/) | Adapter architecture, Run button, SSE streaming, session resume |
| [Security](https://thepixelabs.github.io/dispatch/docs/security/) | G1-G4 security gates, prompt sandboxing, threat model |
| [Contributing](https://thepixelabs.github.io/dispatch/docs/contributing/) | How to contribute, adding new provider adapters, code standards |
### Dispatch Kernel (v1.49+)
The April 2026 orchestration-kernel consolidation. Start here if you're reading
the server code, debugging stuck runs, or integrating with the MCP surface.
| Document | Contents |
|----------|----------|
| [ADR-016 — Run Registry SoT](docs/decisions/ADR-016-run-registry-single-source-of-truth.md) | SQLite `runs` + `run_events` is canonical; `activeRuns` Map and Activity Store are caches |
| [ADR-017 — Event-sourced lifecycle](docs/decisions/ADR-017-event-sourced-run-lifecycle.md) | `run_events` superset schema, idempotency, `Last-Event-ID` replay |
| [ADR-018 — Process-group lifecycle](docs/decisions/ADR-018-process-group-lifecycle.md) | Spawn in own pgid, signal `-pgid`, new `interrupted` terminal |
| [ADR-019 — Synchronous typed MCP](docs/decisions/ADR-019-synchronous-typed-mcp.md) | Idempotency keys, `{kind, retryable, hint}` errors, synchronous spawn admission |
| [ADR-020 — Reaper + hot-crash](docs/decisions/ADR-020-reaper-and-hot-crash-coverage.md) | 60s reaper, uncaughtException → sync SQLite, `server_state.clean` marker |
| [ADR-022 — Hybrid spawn model](docs/decisions/ADR-022-spawn-model-hybrid.md) | Orchestrator-spawn becomes default; observer-mode preserved as back-compat. New `POST /api/runs` endpoint. |
| [ADR-023 — LLM transport: subprocess CLI](docs/decisions/ADR-023-llm-transport-subprocess-cli-first.md) | Subprocess CLI for chat, MCP for tools; vendor SDK explicitly deferred. |
| [ADR-024 — Auth delegation to vendor CLI](docs/decisions/ADR-024-auth-delegate-to-vendor-cli.md) | No key vault, no in-app login; spawn boundary strips `ANTHROPIC_API_KEY`. |
| [ADR-025 — Multi-tool defer](docs/decisions/ADR-025-multi-tool-defer.md) | One CLI per run; cross-vendor coordination is the Workflow Mission Planner's job. |
| [Event Log reference](docs/server/EVENT_LOG.md) | Schema, taxonomy, invariants, canonical APIs |
| [Reaper design](docs/server/REAPER.md) | Three-signal terminal decision + tuning knobs |
| [Lifecycle + crash recovery](docs/server/LIFECYCLE.md) | Hot-crash handlers + boot recovery |
| [MCP Tool Reference](docs/MCP_TOOL_REFERENCE.md) | All 11 tools, error envelope shape |
| [Migration Guide](docs/MIGRATION_GUIDE.md) | DB schema 001..009, apply order, rollback, backup |
| [Operator Runbook](docs/RUNBOOK.md) | Symptom → fix for the 3am case |
| [Design Decisions](docs/DESIGN_DECISIONS.md) | What dispatch is NOT trying to be, rejected alternatives |
## License
This project is fair-code distributed under the **PolyForm Shield 1.0.0 License**.
You may use, modify, and distribute this software for personal and internal business operations. Commercial use is permitted, provided it does not directly compete with the primary product or services offered by the repository owner.
Please refer to the [`LICENSE`](LICENSE) file for the complete terms and conditions.
## Trademarks
Claude Code, GitHub Copilot, Gemini, and OpenAI Codex are trademarks of their respective owners. Dispatch is not affiliated with or endorsed by any of them.
---
<p align="center">
<sub>Made by <a href="https://github.com/thepixelabs">@thepixelabs</a>. Contributions welcome.</sub>
</p>
