Skip to main content
Workers are configured via ~/.dispatch/config.yaml. The config uses a model-centric schema that separates backend commands from model definitions.

​
Config File Location

The configuration file is stored at: 
~/.dispatch/config.yaml
On first run, Dispatch auto-detects your CLIs (claude, agent, codex), discovers available models, and generates this file automatically. No manual config is needed for the happy path.

​
Schema

The config has three main sections: backends, models, and aliases. 
default: opus  # Default model (by name or alias)

backends:
  claude:
    command: >
      env -u CLAUDE_CODE_ENTRYPOINT -u CLAUDECODE
      claude -p --dangerously-skip-permissions
  cursor:
    command: >
      agent -p --force --workspace "$(pwd)"
  codex:
    command: >
      codex exec --full-auto -C "$(pwd)"

models:
  opus:            { backend: claude }
  sonnet:          { backend: claude }
  haiku:           { backend: claude }
  gpt-5.3-codex:  { backend: codex }
  gemini-3.1-pro:  { backend: cursor }

aliases:
  security-reviewer:
    model: opus
    prompt: >
      You are a security-focused reviewer.
  quick:
    model: sonnet

​
Backends

Define CLI commands for each provider. Each backend specifies a command template that will be used to spawn worker agents.

​
Models

One-line entries mapping model names to backends. Adding a new model is just a single line.

​
Aliases

Named shortcuts that resolve to a model and optionally prepend role-specific instructions to the worker prompt.

​
Command Construction Rules

How Dispatch builds the final command depends on the backend:

​
Cursor Backend — Append --model

  1. Look up model (e.g., gemini-3.1-pro) → backend: cursor
  2. Look up backend command → agent -p --force --workspace "$(pwd)"
  3. Append --model gemini-3.1-pro → final command
Result: 
agent -p --force --workspace "$(pwd)" --model gemini-3.1-pro

​
Claude Backend — Do NOT Append --model

  1. Look up model (e.g., opus, or versioned ID like sonnet-4.6) → backend: claude
  2. Use the backend command as-is
  3. Do not append --model — the Claude CLI manages its own model selection
Result: 
env -u CLAUDE_CODE_ENTRYPOINT -u CLAUDECODE claude -p --dangerously-skip-permissions
Appending --model to Claude backend commands can cause access errors due to internal alias resolution. Always omit --model for Claude.

​
Codex Backend — Append --model

  1. Look up model (e.g., gpt-5.3-codex) → backend: codex
  2. Look up backend command → codex exec --full-auto -C "$(pwd)"
  3. Append --model gpt-5.3-codex → final command
Result: 
codex exec --full-auto -C "$(pwd)" --model gpt-5.3-codex

​
For Aliases

For aliases, the alias’s model is resolved the same way, and any prompt addition is prepended to the worker prompt.

​
Model Detection Rules

Dispatch automatically routes models to the correct backend:
Claude model detection: Any model ID containing opus, sonnet, or haiku — including versioned variants (e.g., sonnet-4.6, opus-4.5-thinking) — is a Claude model and must use backend: claude when the Claude Code CLI is available. Never route Claude models through the cursor backend.
OpenAI model detection: Any model ID containing gpt, codex, o1, o3, or o4-mini is an OpenAI model and must use backend: codex when the Codex CLI is available. Only fall back to cursor backend when Codex is not installed.

​
Key Config Patterns

​
Model-Centric Config

Backends define CLI commands once; models map to backends. For Cursor and Codex backends, --model is appended automatically. For Claude backend, --model is omitted (the CLI manages its own model selection). Adding a model is one line.

​
First-Run Setup

On first use (no config file), the dispatcher:
  1. Detects CLIs (agent, claude, codex)
  2. Discovers available models via agent models
  3. Presents options via interactive prompt
  4. Generates the config automatically
No manual YAML writing needed.

​
Smart Model Resolution

If you reference a model not in config, the dispatcher:
  1. Probes availability (agent models)
  2. Auto-adds it to config
  3. Dispatches immediately
No config editing needed.

​
Aliases with Prompt Additions

Named shortcuts (e.g., security-reviewer) that resolve to a model and optionally prepend role-specific instructions to the worker prompt. Example: 
aliases:
  security-reviewer:
    model: opus
    prompt: >
      You are a security-focused reviewer. Prioritize OWASP Top 10
      vulnerabilities, auth flaws, and injection risks.
Usage: 
/dispatch have security-reviewer check my latest changes

​
Natural Language Config Editing

You can edit your config using natural language. The dispatcher reads, edits, and writes ~/.dispatch/config.yaml directly — no special commands needed.

​
Examples

/dispatch add gpt-5 to my config

​
Resulting Config

default: claude

backends:
  cursor:
    command: >
      agent -p --force --workspace "$(pwd)"
  claude:
    command: >
      env -u CLAUDE_CODE_ENTRYPOINT -u CLAUDECODE
      claude -p --dangerously-skip-permissions

models:
  opus:     { backend: claude }
  sonnet:   { backend: claude }
  gpt-5:    { backend: cursor }
  gemini-2.5-pro: { backend: cursor }

aliases:
  speedy:
    model: composer-1.5

​
Backward Compatibility

Old agents: config format is still recognized. Each agent entry is treated as an alias with an inline command. The dispatcher suggests migration to the new format.
See the Multi-Model Support guide for details on how to use different models in your dispatch tasks.

Build docs developers (and LLMs) love

Get started for freeTalk to us