Skip to main content
The config file at ~/.dispatch/config.yaml defines available backends, models, and aliases for worker dispatch. On first run, /dispatch auto-generates this file — no manual configuration required.

​
File Location

~/.dispatch/config.yaml
This file is shared across all projects using /dispatch.

​
Schema Overview

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:
  # Claude
  opus:            { backend: claude }
  sonnet:          { backend: claude }
  haiku:           { backend: claude }
  # GPT / OpenAI
  gpt-5.3-codex:   { backend: codex }
  gpt-5.2:         { backend: codex }
  # Gemini
  gemini-3.1-pro:  { backend: cursor }

aliases:
  security-reviewer:
    model: opus
    prompt: >
      You are a security-focused reviewer.
      Prioritize OWASP Top 10 vulnerabilities.
  quick:
    model: sonnet

​
Fields

​
default

​
default
string
required
The default model to use when no model is specified in the dispatch command. Must match a key in models: or aliases:.
Examples: 
default: opus
default: sonnet
default: security-reviewer  # Can reference an alias

​
backends

​
backends
object
required
Defines CLI command templates for each backend. Each backend has a command field.
​
backends.<name>.command
string
required
The CLI command template to invoke this backend. Use > for multi-line YAML strings.
Built-in backends:
Claude Code CLI backend. Does not append --model flag — the Claude CLI manages model selection internally.
claude:
  command: >
    env -u CLAUDE_CODE_ENTRYPOINT -u CLAUDECODE
    claude -p --dangerously-skip-permissions
The env -u flags prevent nested Claude Code sessions from inheriting environment variables.
Cursor CLI (agent) backend. Appends --model <model-id> automatically.
cursor:
  command: >
    agent -p --force --workspace "$(pwd)"
Final command: agent -p --force --workspace "$(pwd)" --model gemini-3.1-pro
OpenAI Codex CLI backend. Appends --model <model-id> automatically.
codex:
  command: >
    codex exec --full-auto -C "$(pwd)"
Final command: codex exec --full-auto -C "$(pwd)" --model gpt-5.3-codex

​
models

​
models
object
required
Map of model IDs to their backend configuration. Each model is a single line mapping to a backend.
​
models.<model-id>
object
required
Example: 
models:
  opus:            { backend: claude }
  sonnet:          { backend: claude }
  haiku:           { backend: claude }
  gpt-5.3-codex:   { backend: codex }
  gemini-3.1-pro:  { backend: cursor }
Group models by provider using YAML comments for better readability:
models:
  # Claude
  opus:   { backend: claude }
  sonnet: { backend: claude }
  # GPT
  gpt-5.3-codex: { backend: codex }

​
aliases

​
aliases
object
Named shortcuts that resolve to a model and optionally prepend role-specific instructions to the worker prompt.
​
aliases.<alias-name>
object
Example: 
aliases:
  security-reviewer:
    model: opus
    prompt: >
      You are a security-focused reviewer.
      Prioritize OWASP Top 10 vulnerabilities, auth flaws, and injection risks.
  quick:
    model: sonnet
  code-reviewer:
    model: gpt-5.3-codex
    prompt: >
      You are a code reviewer focused on best practices, readability, and performance.
Usage: 
/dispatch "have security-reviewer check my auth module"
# Uses: opus backend with security-focused prompt prepended

​
Backend-Specific Command Construction

How the dispatcher builds the final CLI command depends on the backend:
1

Resolve model to backend

Look up the model in models: to get its backend name.
2

Get command template

Look up the backend in backends: to get the command template.
3

Apply backend rules

  • cursor/codex: Append --model <model-id> to the command
  • claude: Use command as-is (NO --model flag)
backends:
  cursor:
    command: agent -p --force --workspace "$(pwd)"
  claude:
    command: claude -p --dangerously-skip-permissions
  codex:
    command: codex exec --full-auto -C "$(pwd)"

models:
  gemini-3.1-pro:  { backend: cursor }
  opus:            { backend: claude }
  gpt-5.3-codex:   { backend: codex }
Why no --model for Claude?The Claude CLI resolves aliases like opus to specific versioned model IDs internally (e.g., opus → claude-opus-4-6). This resolution can fail if the resolved version isn’t available on your account. Omitting --model lets the CLI use its own default, which always works.

​
Model Detection Rules

When auto-generating config or auto-adding models, the dispatcher applies these detection patterns:
Any model ID containing opus, sonnet, or haiku — including versioned variants.Examples:
  • opus
  • sonnet
  • haiku
  • sonnet-4.6
  • opus-4.5-thinking
  • claude-opus-4-6
Backend preference: When Claude Code CLI is available, ALL Claude models must use backend: claude. Never route Claude models through cursor or codex backends.
Any model ID containing gpt, codex, o1, o3, or o4-mini.Examples:
  • gpt-5.3-codex
  • gpt-5.2
  • gpt-4
  • o1-preview
  • o3-mini
  • o4-mini
Backend preference: When Codex CLI is available, ALL OpenAI models must use backend: codex. Only fall back to cursor backend when Codex is not installed.
Models that don’t match Claude or OpenAI patterns (e.g., Gemini, Anthropic versioned IDs).Examples:
  • gemini-3.1-pro
  • gemini-2.5-flash
  • claude-3-opus-20240229
Backend preference: Use cursor backend when available.

​
Modifying Config

You can modify the config using natural language via /dispatch:

​
Add a Model

/dispatch "add gpt-5.3 to my config"
The dispatcher:
  1. Runs agent models to verify availability
  2. Adds to models: with appropriate backend
  3. Writes updated config

​
Create an Alias

/dispatch "create a security-reviewer alias using opus"
The dispatcher adds to aliases: section: 
aliases:
  security-reviewer:
    model: opus
You can also specify a prompt addition: 
/dispatch "create a quick alias using sonnet with prompt: you prioritize speed over depth"

​
Change Default

/dispatch "switch default to sonnet"
/dispatch "set my default model to gpt-5.3-codex"
Updates the default: field.

​
Remove a Model

/dispatch "remove gpt-5.2 from config"
Deletes the model from models: section.

​
Auto-Discovery

When you reference a model NOT in your config, the dispatcher automatically:
1

Check availability

Run agent models (if Cursor CLI exists) or check known patterns (Claude/Codex CLIs)
2

Auto-add if found

Add the model to models: with the appropriate backend based on detection rules
3

Use immediately

Proceed with dispatch using the newly-added model
4

Notify if unavailable

Tell user the model isn’t available and suggest running agent models to see options
Example: 
/dispatch "use gemini-3.1-pro to review this"
# If gemini-3.1-pro not in config:
# → Runs: agent models
# → Finds: gemini-3.1-pro
# → Adds: gemini-3.1-pro: { backend: cursor }
# → Dispatches using gemini-3.1-pro

​
Backward Compatibility

Old config format using agents: is still recognized: 
default: cursor

agents:
  cursor:
    command: agent -p --force --workspace "$(pwd)"
  claude:
    command: claude -p --dangerously-skip-permissions
  harvey:
    command: agent -p --force --model gpt-5 --workspace "$(pwd)"
When the dispatcher detects the old format, it suggests migrating:
/dispatch "migrate my config"
This converts agents: to the new backends: + models: + aliases: schema.

​
Config Patterns

​
Multi-Provider Setup

Support Claude, OpenAI, and Gemini models: 
default: opus

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

models:
  # Claude
  opus:            { backend: claude }
  sonnet:          { backend: claude }
  haiku:           { backend: claude }
  # OpenAI
  gpt-5.3-codex:   { backend: codex }
  gpt-5.2:         { backend: codex }
  # Gemini
  gemini-3.1-pro:  { backend: cursor }
  gemini-2.5-flash: { backend: cursor }

​
Role-Based Aliases

Define specialized workers for different tasks: 
aliases:
  security-reviewer:
    model: opus
    prompt: |
      You are a security-focused reviewer.
      Prioritize OWASP Top 10, auth flaws, injection risks.
  
  test-writer:
    model: sonnet
    prompt: |
      You write comprehensive unit and integration tests.
      Aim for 80%+ coverage, focus on edge cases.
  
  docs-writer:
    model: haiku
    prompt: |
      You write clear, concise documentation.
      Use examples, avoid jargon.
Usage: 
/dispatch "have security-reviewer check auth.ts"
/dispatch "have test-writer add tests for payments"
/dispatch "have docs-writer update the API reference"

/dispatch Command

Command syntax and usage patterns

Plan Files

How workers track progress

Build docs developers (and LLMs) love

Get started for freeTalk to us