Quick Start

Applies to: Dispatch v1.0.0, last verified 2026-04-05

This walkthrough assumes you have already completed Installation and have at least one supported CLI agent installed (claude, codex, or gemini on your PATH). By the end you will have the dashboard open, a project registered, and at least one agent showing as live.

Step 1: Start the dashboard

cd /path/to/dispatch
npm run dev

Open http://localhost:5173 in your browser. (Production build: open http://localhost:4242 instead.)

Just want to see it?

Register the included sample project to see the dashboard with realistic data (no agents required):

node cli.js add /path/to/dispatch/sample-project --name "Sample Project"

It ships with two epics, phases in DONE / IN_PROGRESS / BLOCKED states, and execution log entries so the dashboard looks populated immediately.

Step 2: Complete first-run setup

On first launch, the Onboarding Flow replaces the main UI. It:

1. Asks where you keep your git projects
2. Scans that directory for repos with a .git folder
3. Lets you select which repos to register in bulk
4. Offers to install bundled agent personas

You can skip any step, or press Escape to skip setup entirely and add projects manually. Once you complete or skip setup, Dispatch writes onboarded: true to ~/.dispatch/config.json and the flow does not appear again.

If you skipped setup and want to add a project: click + Project in the header, or run:

node cli.js add /path/to/your/project --name "My Project"

Step 3: Start an agent

Dispatch supports two spawn paths. Pick whichever fits the moment — both produce rows in the same Run Registry and surface in the same dashboard. See ADR-022 (hybrid spawn model) for the full rationale.

Path A — launch from your terminal (observer mode)

Open a new terminal in your project directory:

cd /path/to/your/project
claude --agent ceo

The vendor CLI writes a JSONL session file. Dispatch’s chokidar watcher reads line 0 to extract the persona and stamps the Run Registry row within ~10 seconds. Watch the dashboard: the @ceo entry in the agent sidebar turns live (green gradient text, animated dot). Liveness for observer-mode runs is derived from JSONL session mtime against a 5-minute staleness threshold.

Start more agents in additional terminals as needed:

# Terminal 2
cd /path/to/your/project
claude --agent staff-engineer

# Terminal 3
cd /path/to/your/project
claude --agent cto

Path B — spawn from the dashboard (orchestrator mode)

Click + New Run in the dashboard, pick a persona from the dropdown, type a prompt, hit spawn. Dispatch launches the CLI as a subprocess, captures the PID, and opens the chat surface for the new runId.

Equivalent over HTTP:

curl -X POST http://localhost:4242/api/runs \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "staff-engineer",
    "prompt": "start phase 3",
    "cwd": "/path/to/your/project"
  }'
# Response: {"runId":"<uuid>"}

The vendor field is optional and defaults to claude. Cancel via POST /api/runs/<runId>/cancel; resume via POST /api/runs/<runId>/resume with the original cwd.

Liveness for orchestrator-spawn runs uses the full liveness triple: Run Registry state + process.kill(pid, 0) PID probe + lastOutputAtMs watermark. This distinguishes “process alive, model thinking” from “process dead” — observer-mode mtime cannot do that alone.

Auth note: Dispatch never reads ANTHROPIC_API_KEY itself. Auth is delegated to the vendor CLI’s existing login state (claude /login, codex auth, etc.). The auth-status indicator in the dashboard header shows whether the spawned vendor is logged in. See ADR-024.

Step 4: Create an epic

Ask the CEO agent to plan some work. When the agent writes a plan.md file to .tasks/<epic-name>/, the epic card appears in the dashboard center column within a few seconds.

A minimal plan.md looks like:

---
epic: my-feature
phases:
  - id: 1
    title: "Design the API"
    persona: system-architect
    status: TODO
  - id: 2
    title: "Implement the API"
    persona: staff-engineer
    status: TODO
---

## Context

Description of what this epic accomplishes.

The dashboard shows a card with the epic name, a status badge, and a phase railroad (one dot per phase).

Step 5: Watch phases complete

As agents claim and complete phases, the dashboard updates live:

• A claimed phase dot turns blue (pulsing)
• A completed phase dot turns green
• The activity feed on the right adds an entry for each completed phase

Click any epic card to open the detail drawer, which shows the full plan prose and execution log side by side.

Step 6: Find your past work

Once you have a few sessions and epics, use search to navigate back to anything.

Press Cmd+K (Mac) or Ctrl+K (Linux/Windows) to open the Command Palette. Type part of a session prompt, epic name, or agent name to jump straight to it.

Cmd+K → type "auth" → press Enter → session drawer opens

For more targeted lookups (for example, “show me all blocked Claude sessions from this week”), press Cmd+Shift+F to open the Search Panel and use the filter chips.

See Search for the full guide.

What you are seeing

UI element	What it shows
Provider filter (header)	Pill toggles to filter by provider: All, Claude, Copilot, Gemini, Codex
Agent sidebar (left)	All agents: live, idle, defined, starting (in-flight spawns), and archived
Epic grid (center)	Every epic in .tasks/, sorted by status. Click a phase’s Run button to spawn an agent.
Activity feed (right)	Completed phase summaries, newest first
Sessions tab (center)	Active sessions from all four providers (Claude, Codex, Copilot, Gemini)

On mobile, a bottom tab bar replaces the multi-column layout. Tab labels: Units (agent sidebar), Ops (epic grid), Feed (activity), Intel (analytics), Spend (cost).

See Sessions and Agent Sidebar for detailed explanations of each panel.