Documentation

Getting Started

Installation

Download the Dispatch desktop app from withdispatch.dev/download. Dispatch is available for macOS (Apple Silicon and Intel) and Linux (x86_64 and ARM64).

On macOS, open the downloaded .dmg, drag Dispatch to your Applications folder and launch it. The first launch may take a moment as the embedded Bun runtime initializes.

On Linux, download the .AppImage or .tar.gz, make it executable and run it directly. No system-wide installation is required.

The dispatch CLI is bundled automatically and becomes available in your terminal after the first launch.

Prerequisites

Dispatch orchestrates AI coding agents. You need at least one installed and authenticated before creating your first goal:

Claude Code is also available via brew install --cask claude-code. Dispatch auto-detects installed CLIs from over 40 common installation paths. You do not need all three - Dispatch works with any combination and routes tasks to whatever is available.

First Launch

When you open Dispatch for the first time, a setup wizard guides you through four steps:

1. Welcome: Introduction to Dispatch and the IOE concept
2. Your Name: Set your display name for personalized greetings
3. Agent Detection: Dispatch scans your system for installed agent CLIs and displays their status
4. Quick Tour: A brief overview of the key views and workflows

No project setup is required during the wizard. You can add projects afterward from the Dashboard or Settings. Subsequent launches open directly to the Dashboard.

The Setup Wizard

The setup wizard runs automatically on first launch. It covers:

• Agent detection: Shows which CLIs are found and their availability. Dispatch auto-detects agents from over 40 common installation paths including Homebrew, npm, Nix, Volta and Cargo.
• Personalization: Set your name for the Dashboard greeting. This can be changed later in Settings.
• Orientation: Quick tour of the Floor, Missions, Goals and the command palette (Cmd+K).

Adding Your First Project

Dispatch works within project directories. To add a project after initial setup:

1. Open Settings (Cmd+,)
2. Go to the Projects section
3. Click Add Project and select the directory

Each project maintains its own goals, missions, decision history and pipeline configuration. You can switch between projects from the sidebar or the command palette (Cmd+K).

Core Concepts

IOE vs. IDE

Dispatch is an Integrated Overview Environment (IOE), not an Integrated Development Environment (IDE). The distinction is intentional and foundational.

An IDE is built around the act of typing: editing files, running tests, reading compiler output. The human is the implementer. An IOE is built around the act of directing: defining goals, reviewing specs, approving outputs and steering agents. The human is the manager.

You can still write code manually at any time. Dispatch detects manual changes and updates the floor state accordingly. The goal is augmentation, not replacement.

Missions

Missions are lightweight, instant agent tasks. Unlike Goals (which go through a full pipeline), Missions dispatch a single agent immediately with no pre-flight stages.

Use Missions for quick tasks that do not belong in a project pipeline: research a library, explain an error, draft a document, audit a file, write a throwaway script or generate a step-by-step plan.

Launching a Mission

• Cmd+M (macOS) or Ctrl+M (Linux) from anywhere in the app
• Click Mission in the sidebar
• Cmd+K then select "New Mission"
• CLI: dispatch mission "your intent"

Mission Modes

Dispatch auto-detects the best mode from your intent. Click the mode badge to override manually.

• Standard: Concise, direct answers. Best for explanations, quick code and drafts. Capped at 1000 tokens for focused responses.
• Research: Structured document with Background, Options, Comparison table, Recommendation and Sources sections. Uses a 4000 token cap for thorough analysis.
• Audit: Security-focused analysis with OWASP-categorized findings. Always read-only. Uses a 4000 token cap.
• Plan: Structures the response as numbered steps that can each be promoted to a Goal and executed through the full pipeline.

Mission Features

• Context inheritance: Optionally pull in your project's conventions and recent decisions
• Read/Write toggle: Missions are read-only by default. Enable write access for code generation tasks (requires a project).
• Minimize: Send a running mission to the background and keep working. The status rail shows progress.
• Promote to Goal: Turn a mission result into a full Goal with a spec seed pre-populated from the mission output.
• Save as .mission file: Export to .dispatch/missions/ for future reference.
• Pattern detection: Repeated similar missions surface methodology suggestions to convert them into reusable workflows.
• Streaming results: The UI shows results as they arrive from the agent in real time.

Goals

Goals are the primary unit of work in Dispatch. A goal is a natural language description of something you want built. Dispatch decomposes it into a structured pipeline with multiple agents handling different stages.

Creating a Goal

1. Press Cmd+N or click New Goal from the Dashboard
2. Describe what you want built in plain language
3. Select the target project and pipeline profile
4. Dispatch generates a functional specification for your review
5. Approve the spec to begin implementation, or request changes

Goal Pipeline Stages

Every goal flows through these stages in sequence:

1. Spec: A functional specification is generated from your goal description. You review and approve before any code is written.
2. Test Spec: Test requirements the implementation must satisfy. Runs in parallel with the Security Spec after spec approval.
3. Security Spec: OWASP-mapped security requirements. Runs in parallel with the Test Spec.
4. Implement: An agent writes the code using XML-structured prompts with TDD directives and your project's style conventions.
5. Frontend: If applicable, a frontend agent builds the UI.
6. Verify: Automated bug, security and performance checks against the spec and test spec.
7. Review: Human-in-the-loop approval with the agent-assisted review workspace.
8. Audit: Post-build security and quality assessment (holistic, cross-task).
9. Merge: Git merge to your target branch.

Pause and Resume

Pause active goals at any time: to switch networks, take a break or reprioritize. Resume picks up where agents left off. Claude sessions are resumed via session ID, preserving full context continuity.

Plans

Plans are structured, step-by-step action items extracted from Mission results. When you run a Mission in Plan mode, the agent structures its response as numbered steps. Each step can be:

• Reviewed and edited before execution
• Promoted to a full Goal and executed through the pipeline
• Approved in bulk (auto-execute all steps in sequence)
• Discarded individually without affecting other steps

Plans bridge the gap between quick exploration (Missions) and full project work (Goals). A typical workflow: run a research mission to explore an approach, generate a plan from the result, then promote each step to a goal for structured implementation.

HITL Review

Human-in-the-loop (HITL) review gates are the mechanism that keeps you in control of what agents commit to your codebase. Every task is classified into one of three tiers based on its blast radius:

• Auto: Low-risk, reversible changes (lint fixes, docs, dependency updates). Auto-approved: no human action required.
• Notify: Medium-risk changes. Proceeds automatically, and you receive a notification to review at your convenience.
• Block: High blast radius, irreversible or cross-boundary changes. A full review modal is required before execution can continue.

Review Workspace

When a task reaches the review stage, Dispatch opens a full-viewport review workspace with four tabs:

• Summary: High-level overview of what the agent did and why
• Checklist: Spec verification items that gate approval on block-tier reviews. Each item must be checked before you can approve.
• Diff: Full file diff with risk classification. Files are tagged high, medium or low risk based on blast radius analysis.
• Conversation: The agent's reasoning trail and any HITL feedback from prior attempts

Anti-rubber-stamp measures prevent hasty approvals. On block-tier reviews, the approve button is disabled until the spec checklist is complete. Review decisions are recorded and visible in the Vault timeline.

"Request changes" injects your comment as context into the agent's next attempt. Multiple pending reviews queue serially: the modal shows an "N more waiting" badge when other tasks are also blocked.

Auto Model

Auto Model is Dispatch's intelligent routing system. Instead of manually choosing which agent handles each task, Dispatch analyzes your intent and selects the best available agent and model automatically.

• Research intents (compare, alternatives, tradeoffs) route to Claude or Gemini (which has native web search)
• Code generation intents (write, implement, refactor) route to Claude or Codex
• Design intents (component, UI, layout) route to Gemini
• Audit intents (security, vulnerabilities, OWASP) route to Claude

Auto Model defaults to speed-first routing for Missions and quality-first routing for Goals. You can override the adapter and model at any time by switching to Manual mode in the mission bar or task settings. Disable Auto Model entirely in Settings if you prefer full manual control.

Sandbox

The Sandbox provides project-level isolation for agent work. All modifications happen in a mirrored copy (git worktree) of your project. The real project is never directly modified during agent runs.

When agent work is complete:

1. Dispatch presents the diff in the review workspace
2. You approve, request changes or reject
3. On approval, the changes are applied to your working directory
4. On rejection, the sandbox is discarded with no side effects

Worktree symlink optimization reduces disk usage for large projects. The sandbox is scoped per-task, so parallel agent runs on the same project do not interfere with each other.

Features

Multi-Adapter Support

Dispatch has first-class adapters for three agent CLIs:

Adapters are detected automatically from your PATH and common installation directories. Custom CLI paths can be set manually in Settings if your installation is non-standard. The adapter availability is cached after the first successful detection and refreshed on each launch.

Performance Corrections

Performance Corrections let you teach agents your preferences while they work. If an agent deviates from your code style, makes a questionable architectural choice or produces output that doesn't match your expectations, you can send a mid-task correction without stopping the run.

Corrections are injected as structured context into the agent's next output cycle. They are recorded in the task history so that future tasks | and future agents picking up the same work | have access to your preferences. Over time, Dispatch surfaces patterns in your corrections as methodology suggestions that you can formalize into pipeline profiles or project conventions.

Remote SSH

Dispatch supports running agents on remote machines via SSH. This is useful when your project lives on a remote server, when you want to use GPU-backed machines for heavy workloads or when you need to run agents in a specific network environment.

Setting Up Remote Hosts

1. Open Settings and go to Remote Hosts
2. Click Add Host and enter the hostname or IP, port and username
3. Dispatch uses your existing SSH keys: it never stores private keys
4. Dispatch will scan the remote host for installed agent CLIs
5. Add a remote project directory from the Projects settings

All communication between Dispatch and remote agents is encrypted via SSH. Remote projects use the same worktree isolation model as local projects. Agent transcripts are streamed back to the local Dispatch UI in real time.

Paper Import

Paper Import allows you to implement research papers directly through Dispatch. Paste a paper URL or upload a PDF, and Dispatch extracts the key algorithm or technique and generates a goal with a spec pre-populated from the paper's methodology.

This is particularly useful for:

• Implementing novel algorithms from academic papers
• Translating techniques described in ML papers into working code
• Using a paper as the formal specification for an implementation task

Environment Bootstrap

Environment Bootstrap injects project context into every agent prompt automatically. When Dispatch starts a new agent run, it assembles a structured context package that includes:

• Your project's tech stack and conventions (from CLAUDE.md, AGENTS.md or GEMINI.md if present)
• The active goal and approved spec
• The test spec and security spec requirements
• A compaction summary if the prior session was compacted
• Relevant decisions from the Vault for the files being changed

This ensures agents always have the right context to produce consistent, spec-compliant output | even across session boundaries, agent handoffs or compaction events.

Decision Tracking

Dispatch records every decision agents make during implementation, creating a complete audit trail for each goal.

• Task start: When an agent begins work and which adapter was assigned
• File changes: Every file created, modified or deleted with timestamps
• Verify results: Automated check outcomes (pass, warn, fail)
• Review outcomes: Approval, rejection or reassignment decisions with reviewer comments
• Deviations from spec: Cases where the implementation diverged from the approved specification

Decisions are viewable in the Vault as color-coded cards. Each card shows the timestamp, decision type, affected files and any deviations. Use the Lore Decision Query to search decision history for specific files or constraints.

Token Efficiency

The Observatory tracks token usage across every adapter and task, with a dedicated Token Efficiency section.

• Cache hit ratio: Percentage of tokens served from cache vs. fresh generation
• Estimated savings: Dollar-amount savings from cache hits across all adapters
• Per-adapter breakdown: Token efficiency metrics for Claude, Codex and Gemini independently
• Per-task efficiency: Token usage and cache performance for individual tasks
• Red flag alerts: Warnings when cache ratio drops below 30%, indicating potential prompt instability

Dispatch optimizes token usage by maintaining stable tool ordering and consistent settings across agent runs, maximizing cache reuse.

In-App Preview

Preview completed goals directly within Dispatch. When a goal reaches the completed or approved stage, the preview option becomes available.

• Dispatch spawns a dev server for the project automatically
• Opens a new window with the running application
• Available on goals with a completed or approved status

This lets you verify the result visually before merging, without leaving the IOE.

Views

Dashboard

The default landing view. Shows an at-a-glance summary of active goals, recent activity, pending reviews and agent status. Start new goals or missions directly from the Dashboard.

Floor (Cmd+1)

Live monitoring of agent activity across pipeline stages. Two layout modes:

• Feed view (default): Chronological activity stream showing agent events as they happen
• Board view: Horizontal swimlanes organized by pipeline stage (Spec / Implement / Frontend / Review)

Click any card to open the Focus Panel with detailed reasoning, file changes and intervention controls.

Floor 3D (Cmd+2)

Immersive 3D command center with fullscreen HUD. Features interactive cubicles representing active agents, a goals sidebar, reviews panel, telemetry readout and quick goal launcher. Navigate with WASD keys, toggle HUD with H and toggle fullscreen with F.

Agentflow (Cmd+3)

Agentflow (Cmd+3) pipeline timeline visualization showing goal-to-spec-to-task dependency trees. Each node represents a pipeline stage with its current status. Click any node for details including timing, agent assignment and output.

Task Board (Cmd+4)

Kanban-style board for tracking all tasks across goals, with separate sections for active and archived tasks. Filter by status, agent or goal.

Vault (Cmd+5)

Decision replay browser. View the full decision trail for any completed task, displayed as a color-coded timeline. Includes the Lore Decision Query for file-level constraint and rejection history.

Observatory (Cmd+6)

Metrics dashboard: token usage, cost estimation, pipeline velocity, quality signals, actionable insights and a dedicated Token Efficiency section tracking cache hit ratios and per-adapter savings.

Configuration

Settings Reference

Pipeline Automation

• Skip spec review: Auto-approve specs without manual review. Disabled by default. Enable only for low-stakes projects where you trust the decomposer.
• Dual-agent security: Run Codex as a second opinion after Claude's verify pass. Increases security coverage at the cost of additional token usage.
• Token budget: Maximum tokens per task. Set to 0 for unlimited. Useful for controlling costs on large codebases.
• Auto Model: Intelligent agent and model selection based on task intent. On by default. Disable for full manual control.

Remote Access

• Browser access: Allow network connections to the Dispatch UI. Disabled by default. Dispatch is a desktop-first application.
• HTTPS: Auto-generates a self-signed TLS certificate for secure browser access when enabled. The Settings page provides CA certificate download instructions for trusted connections on other devices.

Notifications

• Notify-tier reviews: Desktop notification when a task reaches notify-tier review. Off by default.
• Goal completion: Notification when a goal reaches the merge stage. Off by default.
• Agent errors: Notification when an agent run fails. Off by default.

Pool Configuration

• Max concurrent: Total simultaneous agent runs across all goals and projects.
• Max per goal: Maximum simultaneous agent runs for a single goal (controls parallelism within the test/security spec stages).

System Tray

• Menu bar icon: Show Dispatch status in the macOS menu bar. On by default on macOS. Not available on Linux.

Pipeline Profiles

Pipeline profiles define which agent handles each stage of the goal pipeline. Create multiple profiles for different project types and switch between them per-project or per-goal.

Create a custom profile in Settings > Pipeline Profiles. Per-task agent override is always available regardless of the active profile.

Agent Pool Configuration

The agent pool controls how many agents run concurrently. The defaults are conservative to avoid exhausting rate limits on your agent subscriptions:

• Max concurrent runs: 3
• Max runs per goal: 2
• Per-adapter rate limiting: automatic, based on detected subscription tier

Increase concurrency if you have multiple projects actively running goals and your agent subscriptions support it. Decreasing concurrency is useful on slower machines or when you want more predictable token spend.

CLI Commands Reference

The dispatch CLI is bundled with the desktop app and available after first launch. All commands are thin wrappers over the local API and work whether the desktop app is open or running headlessly.

# Goal management
dispatch goal "Build auth module"          # Create a new goal
dispatch goals                              # List all goals
dispatch goals --status active             # Filter by status

# Task management
dispatch tasks pending                      # List pending tasks
dispatch tasks --goal <goal-id>            # Tasks for a specific goal
dispatch approve <task-id>                 # Approve a blocked review
dispatch reject <task-id> "reason"        # Reject with feedback

# Missions
dispatch mission "explain rate limiting"   # Run a standard mission
dispatch mission "compare prisma vs drizzle" --research
dispatch mission "audit src/auth.ts" --audit --attach src/auth.ts
dispatch mission list                       # List recent missions
dispatch mission promote <id>             # Promote mission to goal

# Agent status
dispatch status                             # Overall system status
dispatch agents                             # List active agent runs
dispatch logs <agent-run-id>              # Stream agent transcript

# Server management
dispatch start                              # Start Dispatch (default)
dispatch start --server --domain dispatch.yourdomain.com

# Tokens (server mode only)
dispatch token create --name "phone" --readonly
dispatch token list
dispatch token revoke <token-id>

# Pool
dispatch pool status
dispatch pool pause
dispatch pool resume

# Projects
dispatch projects                           # List projects
dispatch projects add /path/to/project     # Add a project

Architecture

High-Level Overview

Dispatch is a monorepo of composable libraries with the app as a consumer. Libraries are published under @dispatch/* and are independently usable. The app layer imports from packages; packages never import from the app layer.

Data Model

All data is stored in a local SQLite database at ~/.dispatch/dispatch.db.

WebSocket Events

The client connects to the server via WebSocket at ws://localhost:<port>/ws. All real-time state updates | agent progress, task status changes and review notifications | are delivered via WebSocket. The client uses an optimistic update model: local state updates immediately, then reconciles with server-confirmed events.

Key event types broadcast over WebSocket:

• agent:token | Streaming token from an active agent run
• agent:status | Agent run status change (started, completed, failed)
• task:status | Task status change
• goal:status | Goal status change
• review:pending | A block-tier review is waiting for approval
• pool:status | Agent pool capacity update

API Reference Summary

The local REST API is available at http://localhost:<port>. In local mode, no authentication is required. In server mode (browser access enabled), all endpoints except GET /health require a Bearer token.

Keyboard Shortcuts