Frequently Asked Questions

IDE vs. IOE

Dispatch isn't just another editor; it's an Integrated Overview Environment (IOE). Here is how it differs from the traditional development workflow:

General

What agents does Dispatch support?

Currently, Dispatch has first-class adapters for Claude Code, OpenAI Codex and Gemini CLI. It can also detect and orchestrate custom CLI-based agents via the Adapters settings.

Does my code leave my machine?

No. Dispatch is local-first. It orchestrates the CLIs already installed on your system. Your source code and agent transcripts are stored in a local SQLite database at ~/.dispatch/dispatch.db.

Can I still write code manually?

Absolutely. Dispatch is designed to augment your workflow, not replace your ability to intervene. You can jump into any file at any time. Dispatch will detect your manual changes and update the "Floor" state accordingly.

How is this different from Cursor or Windsurf?

Cursor and Windsurf are AI-native editors: they excel at helping you write code line-by-line. Dispatch is an Orchestration Layer. It doesn't want to be your only editor; it wants to be the cockpit where you direct multiple specialized agents (like Claude Code and Codex) through a formal pipeline with gated reviews.

What is "Spec-DD"?

Spec-Driven Development (Spec-DD) is the core workflow of Dispatch. Instead of asking an agent to "fix a bug," you ask it to "write a spec for this bug fix." Once you approve the spec, the agent implements it. This ensures the agent's "mental model" matches your expectations before a single line of code is changed.

What is the "Floor"?

The Floor is the visual heart of Dispatch. It's a live monitoring view where every active agent run is visualized as a swimlane. You can see what the agent is thinking, what tools it's calling and where it is in the pipeline (Spec, Implement, Verify, Review) in real-time.

Do I need all three agents installed?

No. Dispatch works with any combination of Claude Code, Gemini CLI and Codex. If you only have Claude installed, Dispatch will route all tasks to Claude automatically. The auto-model system detects which agents are available and selects the best one from what you have. You can always add more agents later from Settings.

What is 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 agent and model automatically. Research queries route to Gemini (native web search), code generation to Claude or Codex, security audits to Claude Opus. You can override this at any time by switching to Manual mode in the Mission bar.

What is a Mission?

Missions are quick, one-shot agent tasks. Ask a question, get an answer. Research a topic, audit code, generate a plan. Unlike Goals (which go through the full pipeline), Missions are ephemeral and fast. Results can be promoted to Goals or turned into step-by-step Plans for execution.

What are 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 promoted to a Goal and auto-executed through the pipeline. Plans bridge the gap between quick questions and full project work.

Can Dispatch run agents on remote machines?

Yes. Dispatch supports remote agent execution via SSH. Add remote hosts in Settings, and Dispatch can discover and run agents installed on those machines. All communication is encrypted via SSH, and Dispatch uses your existing SSH keys (never stores private keys). Remote projects use the same worktree isolation model as local projects.

Can I add my own agents?

Yes. Open Settings > Agents > Add Agent and register any CLI tool that accepts a prompt and produces output. Configure the command, args template with placeholders, output format and an optional health check. Once registered, custom agents appear in pipeline profile dropdowns and the mission bar adapter selector alongside Claude, Codex and Gemini.

Does Dispatch scan for leaked secrets?

Yes. Dispatch includes built-in secret scanning with approximately 50 regex patterns plus entropy analysis. It runs automatically on every agent run with no external tools or configuration required. When a secret is detected, the task is blocked and findings are shown in the review modal. You can optionally register a local LLM (such as Ollama) as a verification agent to reduce false positives without sending sensitive data to cloud APIs.

Can I use local LLMs with Dispatch?

Yes. Register any local agent (Ollama, LM Studio, Aider or any CLI wrapper) via Settings > Agents > Add Agent. Configure the command, args template and output format. Once registered, local agents can be assigned to pipeline stages, used for missions, selected for secret verification and included in Auto Model routing. All processing stays on your machine.

Does Dispatch work with Aider/Ollama/local LLMs?

Yes, via custom agent registration. Any CLI that accepts a prompt argument and returns text or JSON output can be registered as an adapter. This includes tools like Aider, Ollama, LM Studio and any wrapper script you write around a local model.

How does the Sandbox work?

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. When work is complete, you review the changes and explicitly apply them. If something goes wrong, simply discard the sandbox. For stronger isolation, enable Docker sandbox mode in Settings > Workspace Isolation > Docker - agents run in ephemeral containers with network isolation.

What is Docker sandbox mode?

Docker sandbox mode is an optional upgrade from the default git worktree isolation. When enabled, each agent session runs in an ephemeral container with its own filesystem, network and resource limits. Network access is disabled by default inside the container. Enable it in Settings > Workspace Isolation > Docker. Requires Docker Desktop, Colima or OrbStack installed on your machine.

Can I run multiple missions at once?

Yes. Dispatch supports multi-mission tabs. Each tab runs independently with its own adapter, mode and context. You can switch between active missions without interrupting them. The agent pool manages concurrency limits automatically.

How do I test my Dispatch integration?

Dispatch ships with a ReplayAdapter for deterministic testing. Record a real agent session to a JSON fixture file, then replay it in your test suite without hitting any LLM. This lets you test the full orchestration pipeline (DB writes, WebSocket events, output parsing) cheaply and reliably in CI.

Is Dispatch open source?

No. Dispatch is proprietary, closed-source software. We may open up parts of the ecosystem (for example, reference adapters or the replay SDK) over time, but the Dispatch app itself is not source-available today. See Terms and EULA for the full license grant.

What happens when an agent can't solve a problem?

Dispatch auto-escalates to a stronger model. If Claude Haiku can't fix a complex bug, Dispatch retries with Claude Sonnet (better reasoning), then Claude Opus if needed. Each retry carries forward the context and feedback from the prior attempt. After exhausting all model tiers within an adapter, Dispatch notifies you. You can also manually click "Try stronger model" on any failed task to trigger escalation yourself.

Why does Dispatch need git?

Git enables sandbox isolation (worktrees), decision tracking, verify diffs and replay. Every agent run happens in a git worktree mirror of your project, so the real codebase is never modified directly. The status bar shows your project's git state with a color-coded badge (green for clean, amber for uncommitted changes, red for no git). Non-git projects can still run missions but cannot use the full goal pipeline.

How does the Security view work?

The Security view consolidates security findings from the verify pipeline into one dashboard. It shows a pass/warn/fail gate based on unresolved findings, per-finding details with severity and category, and secret allowlist management. The gate badge on the sidebar nav item updates in real time so you always know the current security status without opening the view.

What is Dispatch Pro?

Dispatch Pro ($20/month) adds cloud-hosted AI models, adversarial verification, ML-based routing, and LLM-powered reflection. All local features remain free. Cloud models always use worktree isolation and require human review. No prompt content is logged or cached.

What is Dispatch Team?

Dispatch Team ($50/seat/month, minimum 2 seats) adds everything in Pro plus organization features: shared projects across team members, team HITL review with assignment routing, SSO via GitHub Organizations, audit log with export, per-member usage caps, admin dashboard, and Bring Your Own Keys (BYOK) support. See pricing for the full comparison.

Do I need Pro or Team to use Dispatch?

No. Dispatch is fully functional without Pro or Team. All local agent orchestration, pipeline features, review gates, verification, Floor view, Observatory, Vault, Sessions, CLI, and remote SSH execution are free. Pro is for developers who want additional model diversity. Team is for organizations that need shared projects, SSO, and centralized management.

How does team billing work?

Team is billed per seat at $50/seat/month with a minimum of 2 seats. Seats are prorated when added mid-cycle. Remove seats at any time and billing adjusts on your next invoice. The org admin manages seats from Settings > Organization.

What's included in the Team plan?

Everything in Pro, plus: shared projects, team HITL review with assignment routing, shared project memory and learnings, organization settings and security policies, SSO via GitHub Organizations, audit log with export, per-member usage caps, admin dashboard, and BYOK support.

Can I use my own API keys?

Yes. Team plan includes Bring Your Own Keys (BYOK) support. Add your own API keys for cloud model inference. BYOK usage is excluded from your team pool limits. Keys are encrypted at rest and never logged or returned after submission.

Does Dispatch support SSO?

Yes. Team plan includes SSO via GitHub Organizations. Members of your GitHub org are auto-provisioned when they join and auto-deprovisioned when removed. SSO enforcement can be required for all org members by the admin.

How does Dispatch work with agent CLIs?

Dispatch orchestrates your locally installed agent CLIs (Claude Code, Gemini CLI, Codex). It does not replace them. When you create a goal, Dispatch decomposes it into specs and tasks, then spawns the appropriate CLI process with the right prompt, context files, and project directory. It monitors each agent's output for errors, stuck states, and compaction. It auto-steers when agents ask for permission. It manages concurrency so multiple agents can work in parallel without conflicts. And it verifies output before presenting it for your review. Your agent CLIs handle the AI -- Dispatch handles the orchestration.

What happens when I hit my Pro usage limit?

At 80% usage, you see a warning badge in the StatusRail. At 100%, cloud requests auto-downgrade to the lightest available model instead of blocking. Your local adapters (Claude, Gemini, Codex) are never affected. Limits reset on your billing cycle date.

Is my code sent to the cloud with Pro?

Only when you explicitly select a cloud model. Free tier users never contact cloud infrastructure. When using a cloud model, prompts and tool results are sent to Dispatch's cloud infrastructure for inference. Dispatch does not log, cache, or retain prompt content. Only usage metadata (model, token count, latency, cost) is stored for billing. Cloud models have stricter security than local adapters: mandatory worktree isolation, no auto-approve, destructive command blocking, and 60-second shell timeouts.

How do I report a bug?

Press Cmd+Shift+> in the app, or use Command Palette > "Report an Issue", or Help > Report Issue. The reporter auto-collects diagnostics (version, platform, adapter status) and lets you paste screenshots. All file paths are redacted and no secrets are included. Reports are saved locally and optionally sent to the Dispatch team.

What is the Adversarial Verification Network?

The Adversarial Verification Network (AVN) is a multi-agent cross-verification system available with Dispatch Pro. Instead of one agent verifying implementation quality, AVN dispatches 2-3 independent verifiers that review the same code from different perspectives. Findings they all agree on are auto-resolved. Disputed findings -- where verifiers genuinely disagree -- are surfaced to you in a focused review. You only review the contested items, which dramatically reduces review fatigue. See the docs for details.

How does Dispatch recover from agent crashes?

Dispatch's Managed Agents layer handles this automatically. Agent sessions are periodically checkpointed (transcript, file changes, progress state). When a session terminates unexpectedly -- crash, network error, machine sleep -- Dispatch restarts the session and resumes from the latest checkpoint. Claude sessions are resumed via session ID for full context continuity. You can always manually cancel a recovering task if you want to stop retries. See Managed Agents in the docs.

How does Predictive Routing work?

Dispatch tracks the outcome of every agent run: success rate, token efficiency, verify pass rate and time to completion. Over time, it builds a per-project performance profile for each adapter. When a new task is created, Dispatch routes it to the agent with the best historical performance for similar work. You can optimize for speed, cost or quality in Settings. v1 (rule-based) is free for all users. v2 (ML-based scoring) is a Dispatch Pro feature. See the docs.

How do I connect GitHub to Dispatch?

Open Settings > GitHub and click Connect GitHub Account. Dispatch uses the standard GitHub device flow: a code appears in the app, you enter it on GitHub's website and authorize the OAuth app. Once connected, you can auto-create PRs from completed goals, import GitHub issues as goals and receive GitHub review comments as HITL feedback in Dispatch. Disconnect at any time from Settings. See GitHub Integration in the docs.

What happens when verifiers disagree?

When the Adversarial Verification Network (AVN) dispatches multiple verifiers and they produce conflicting findings, Dispatch surfaces only the disputed items for your review. Unanimous findings (all verifiers agree it passes or fails) are auto-resolved. This means you focus your attention on the genuinely ambiguous cases rather than reviewing the full verification output. AVN is a Dispatch Pro feature.

How does cloud tool execution work?

When you use a cloud model with Dispatch Pro, tool execution can run entirely server-side instead of on your machine. Here's the flow:

1. Upload -- Dispatch uploads your project's context files to an ephemeral cloud workspace. Each file includes a hash for conflict detection.
2. Tool loop -- The cloud model reads, writes, and edits files in the workspace (up to 20 iterations). No shell access -- file operations only.
3. Return -- Modified files come back with their original hashes. The workspace is deleted immediately.
4. Verify -- Dispatch checks each returned file against your local copy (hash match), scans for leaked secrets, and stages changes in a worktree.
5. Review -- You see the diff and approve or reject. Nothing touches your project until you approve.

Your code is only stored during the session and auto-deleted when done. Cloud tool execution is optional, Pro-only, and disabled by default.

What is Reflection?

Reflection is a periodic background process that consolidates your project's memory. It runs automatically after every 10 completed tasks or 24 hours since the last reflect, whichever comes first. Reflection works in five phases: Scan (review recent outcomes), Gather (collect patterns and decisions), Synthesize (detect contradictions and generate new insights), Consolidate (merge related memories) and Prune (remove stale or redundant entries). Free users get basic pruning (no LLM required). Pro users get full LLM-powered synthesis that generates reflect reports with actionable insights. You can also trigger it manually with dispatch reflect.

How do I access Learning Mode and Memory?

Learning Mode is a real-time observation panel that shows agent decisions as they happen. Open it from the Command Palette (Cmd+K, then "Learning Mode") or press Cmd+L. It streams agent reasoning, tool calls, file operations, and decision points while agents are running. Learning Mode is a Dispatch Pro feature.

For periodic memory consolidation, use Reflect. Open it from the Command Palette (Cmd+K, then "Reflect") or run dispatch reflect from the CLI. Reflect scans recent outcomes, gathers patterns, synthesizes new insights, consolidates related memories, and prunes stale entries. It runs automatically after every 10 completed tasks or 24 hours, whichever comes first. Free users get basic pruning. Pro users get full LLM-powered synthesis with actionable reflect reports.

Why are CLI agents slower than cloud models?

CLI agents (Claude Code, Codex, Gemini CLI) run as local processes on your machine. Their speed depends on the underlying model's processing time, network latency to the provider's API, and the complexity of the task. Spec generation and code review are inherently slower because the agent does thorough analysis. Cloud models (Dispatch Pro) skip the CLI overhead and call the inference API directly, which is typically faster for simple queries. For complex tasks, both approaches take similar time because the bottleneck is the model's reasoning, not the transport layer.

Does Dispatch support Windows?

Yes. Dispatch supports macOS 12+, Linux (x86_64 and ARM64), and Windows. See the Download page for the latest installers.