Skip to main content
The /dispatch command is the primary interface for delegating tasks to background AI workers. It accepts natural language task descriptions and automatically plans, dispatches, and monitors work.

​
Basic Syntax

The simplest form of /dispatch takes a task description: 
/dispatch "task description"
Examples: 
/dispatch "do a security review of this project"
/dispatch "refactor the auth module to use JWT"
/dispatch "write unit tests for the API endpoints"
/dispatch "fix a typo in README.md"
The dispatcher immediately returns control to you after spawning the worker. You don’t wait for completion.

​
Model Selection Syntax

You can specify which model to use for a task by mentioning it in your prompt: 
/dispatch "use [model] to [task]"
/dispatch "have [model] [task]"
Examples: 
/dispatch "use gemini-3.1-pro to review the API layer"
/dispatch "have opus do a security review"
/dispatch "use sonnet to write tests for auth.ts"

​
Model Resolution Logic

1

Scan the prompt

The dispatcher scans your prompt for any model name or alias defined in ~/.dispatch/config.yaml.
2

Resolve to command

If a model or alias is found:
  • For a model: Look up its backend, get the backend’s command template
  • For an alias: Resolve to the underlying model, then get the backend command
  • Apply backend-specific rules (cursor/codex: append --model, claude: no --model flag)
3

Auto-discover if needed

If you reference a model NOT in config:
  • If Cursor CLI exists: Run agent models to check availability
  • If found: Auto-add to config with appropriate backend and use it
  • If not found: Tell user the model isn’t available
4

Use default if unspecified

If no model mentioned: Use the default model from config (asks for confirmation first)

​
Multiple Model Mentions

If multiple models are mentioned in a single prompt, the last matching model in the config is used. 
/dispatch "have opus review and sonnet test the auth module"
# Uses: sonnet (last mentioned)
For truly parallel execution with different models, dispatch separate tasks instead.

​
Config Requests vs Task Requests

The dispatcher determines what you’re asking for before taking action:
Mentions keywords like “config”, “add agent”, “add to my config”, “change model”, “set default”, “add alias”, “create alias”Behavior: Reads and modifies ~/.dispatch/config.yaml inline, then stops. No worker is spawned.Examples:
/dispatch "add gpt-5.3 to my config"
/dispatch "switch default to sonnet"
/dispatch "create a security-reviewer alias using opus"
/dispatch "change my default model to gemini"
Any request that doesn’t match config patterns.Behavior: Creates a plan file, spawns a background worker, monitors progress.Examples:
/dispatch "review this code"
/dispatch "implement OAuth login"
/dispatch "write documentation"
Never handles task requests inline. Even simple tasks go through the plan-and-dispatch flow. This ensures non-blocking execution — the core value of /dispatch.

​
Command Patterns

​
Security & Reviews

/dispatch "do a security review of this project"
/dispatch "have security-reviewer check my latest changes"
/dispatch "audit dependencies for vulnerabilities"

​
Refactoring

/dispatch "refactor the auth module to use JWT"
/dispatch "modernize the build system to use Vite"
/dispatch "convert class components to hooks"

​
Testing

/dispatch "write unit tests for the API endpoints"
/dispatch "add integration tests for the checkout flow"
/dispatch "increase test coverage to 80%"

​
Documentation

/dispatch "update the README to reflect recent changes"
/dispatch "write API documentation for the new endpoints"
/dispatch "document the deployment process"

​
Parallel Tasks

/dispatch "review auth.ts"
/dispatch "write tests for payments.ts"
/dispatch "update deployment docs"
Each dispatch command creates a separate worker. All three tasks above run in parallel.

​
First-Run Setup

When ~/.dispatch/config.yaml doesn’t exist, the first /dispatch command triggers auto-setup:
1

Detect CLIs

Checks for available CLIs: agent (Cursor), claude (Claude Code), codex (OpenAI)
2

Discover models

  • If Cursor CLI: Run agent models to list all available models
  • If only Claude Code: Use stable aliases (opus, sonnet, haiku)
  • If Codex CLI: Use known OpenAI model IDs
3

Present options

Show available models and ask which should be your default (via interactive prompt)
4

Generate config

Create ~/.dispatch/config.yaml with all detected models and your chosen default
5

Continue

Proceed with your original dispatch request — no restart needed

​
Status Checking

After dispatching, you can check progress at any time: 
/dispatch "status"
/dispatch "check"
/dispatch "how's it going?"
The dispatcher reads the plan file and reports:
  • Which items are completed ([x])
  • Which item is in progress (first [ ])
  • Any blockers ([?]) or errors ([!])

​
Adding Context to Running Tasks

If you need to provide additional context after dispatching: 
> /dispatch "update the API docs"
> Dispatched `update-api-docs` using opus...

> "also note it's installed via npx skills"
The dispatcher appends your context as a note to the plan file. The worker reads the plan file as it works, so appended notes are visible before it reaches subsequent checklist items.
Do NOT try to inject context via the IPC directory — IPC is worker-initiated only. The worker writes questions, the dispatcher writes answers.

​
Backend-Specific Command Construction

How the final CLI command is constructed depends on the backend: 
# Model: gpt-5.3-codex → backend: cursor
# Command template: agent -p --force --workspace "$(pwd)"
# Final: appends --model flag
agent -p --force --workspace "$(pwd)" --model gpt-5.3-codex
Why no --model for Claude? The Claude CLI resolves aliases like opus to specific versioned model IDs internally. Omitting --model lets the CLI use its own default, which always works.

​
Error Handling

When a worker fails to start or errors immediately:
1

Detect the failure

Worker exits with no items checked off in the plan file
2

Check CLI availability

Verify the required CLI is still installed and authenticated
3

Offer alternatives

List other models/backends available in your config
4

Auto-recover

If you choose an alternative, the dispatcher updates your config default and retries

Config File Reference

Complete schema documentation for ~/.dispatch/config.yaml

Plan Files Reference

Plan file format, markers, and IPC protocol

Build docs developers (and LLMs) love

Get started for freeTalk to us