Skip to main content

​
Prerequisites

Claude Code is required as the host. Dispatch runs as a skill inside Claude Code. The host session plans tasks and spawns workers.
Required: Optional (for multi-model dispatch):
  • Cursor CLI (agent) — access to GPT, Gemini, and other models
  • Codex CLI (codex) — OpenAI models
  • Any CLI that accepts a prompt argument
You need at least Claude Code installed. Worker CLIs (Cursor, Codex) are optional—Dispatch can use Claude Code as both host and worker.

​
Installation

Install Dispatch using the skills CLI: 
npx skills add bassimeledath/dispatch -g

​
User-level vs Project-level

  • User-level (-g): Available in all your projects. Config stored at ~/.dispatch/config.yaml
  • Project-level: Installed in .claude/skills/dispatch. Config still at ~/.dispatch/config.yaml (user-specific)
Even for project-level installs, the config file is user-level (~/.dispatch/config.yaml). This prevents committing API keys or personal model preferences to version control.

​
First-Run Setup

On first use, Dispatch automatically:
  1. Detects available CLIs (claude, agent, codex)
  2. Discovers models by running agent models (if Cursor is available)
  3. Asks you to choose a default model
  4. Generates ~/.dispatch/config.yaml with all detected models
1

Trigger first-run setup

Run any dispatch command:
/dispatch test the first-run setup
2

Dispatch detects your CLIs

Found Cursor CLI (15 models) and Claude Code. Notable models:
  - opus (Claude) — best for complex tasks
  - sonnet (Claude) — fast and capable
  - gpt-5.3-codex (GPT) — strong for code

Which model should be your default?
  1. opus (Recommended)
  2. sonnet
  3. gpt-5.3-codex
3

Choose your default model

Type your choice (e.g., opus)
4

Config is generated

Config created at ~/.dispatch/config.yaml with 15 models. Default: opus.
Dispatched test-setup using opus. Plan: ...

​
Configuration File

Dispatch generates ~/.dispatch/config.yaml with this structure: 
default: opus  # Your chosen default model

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 (stable aliases - auto-resolve to latest version)
  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, auth flaws, and injection risks.

​
Config Sections

CLI commands for each provider. Dispatch routes models through the appropriate backend:
  • Claude backend: No --model flag appended (CLI manages model selection)
  • Cursor backend: --model <id> appended automatically
  • Codex backend: --model <id> appended automatically
One-line entries mapping model names to backends:
models:
  opus:           { backend: claude }
  gpt-5.3-codex:  { backend: codex }
  gemini-3.1-pro: { backend: cursor }
To add a model: just add a line. Dispatch auto-discovers models if you reference one that’s not in config.
Named shortcuts with optional role prompts:
aliases:
  security-reviewer:
    model: opus
    prompt: >
      You are a security-focused reviewer...
Use in dispatch commands: /dispatch have security-reviewer audit the auth flow

​
Modifying Config

You can edit ~/.dispatch/config.yaml manually, or use natural language: 
/dispatch add gpt-5.3 to my config
/dispatch create a security-reviewer alias using opus
/dispatch switch default to sonnet
Dispatch reads, edits, and writes the config file directly—no special commands needed.

​
Verification

Verify your installation:
1

Check that dispatch is available

In Claude Code, type /dispatch and you should see autocomplete or skill detection.
2

Run a test dispatch

/dispatch use sonnet to list all files in the current directory
3

Check for the plan file

cat .dispatch/tasks/*/plan.md
You should see a checklist with items being checked off.
4

Wait for completion

The dispatcher will report when the task is done:
list-files complete. Found 23 files.
Full report at .dispatch/tasks/list-files/output.md
The .dispatch/ directory is ephemeral. Delete it anytime to clean up task files.

​
Updating

Update Dispatch to the latest version: 
npx skills update
This updates all installed skills. Run npx skills check first to see what’s changed.

​
Symlinked to a local clone?

If your .claude/skills/dispatch is a symlink to a local git checkout, just pull: 
cd /path/to/your/dispatch && git pull
Changes are picked up immediately—Claude Code hot-reloads skills from disk.

​
Next Steps

Quickstart

Get to a working example in under 5 minutes

Configuration Guide

Learn about backends, models, and aliases

Build docs developers (and LLMs) love

Get started for freeTalk to us