Skip to main content
Dispatch is a skill (/dispatch) for Claude Code that decomposes large coding tasks into subtasks, dispatches them to background AI worker agents, and tracks progress via checklist-based plan files.

​
Components

Dispatch consists of several key components that work together to enable background task execution:

​
Dispatcher Session

The dispatcher runs in your active Claude Code session. It handles:
  • Creating task plans with checklists
  • Spawning background worker agents
  • Monitoring task progress
  • Managing bidirectional communication with workers
  • Reporting results back to you

​
Worker Agents

Workers are background AI agents that execute the actual work. They can run using different CLIs:
  • Claude Code (claude) - Native Claude models (opus, sonnet, haiku)
  • Cursor (agent) - Multi-model support (Claude, GPT, Gemini, etc.)
  • Codex (codex) - OpenAI models (GPT-5.3, o1, etc.)
Each worker:
  • Reads its assigned plan file
  • Works through checklist items sequentially
  • Updates the plan file as it progresses ([ ] → [x])
  • Can ask questions via IPC without losing context
  • Writes completion markers when done

​
Plan Files

Plan files (.dispatch/tasks/<task-id>/plan.md) are the single source of truth for task state: 
# Security Review

- [x] Scan for hardcoded secrets
- [x] Review authentication logic
- [ ] Check dependency vulnerabilities
- [ ] Write findings to output.md
Checklist markers:
  • [x] - Completed
  • [ ] - Pending or in progress
  • [?] - Blocked (needs user input)
  • [!] - Error encountered

​
Monitor Process

A lightweight bash script monitors each task’s IPC directory:
  • Polls for unanswered questions from the worker
  • Exits when a question is detected, triggering a notification
  • Exits cleanly when the task completes (.done marker found)
  • Times out after 30 minutes of inactivity

​
IPC Directory

The .dispatch/tasks/<task-id>/ipc/ directory enables bidirectional communication:
  • Workers write questions (001.question, 002.question, …)
  • Dispatcher writes answers (001.answer, 002.answer, …)
  • Workers acknowledge answers (001.done, 002.done, …)
  • Completion marker (.done) signals all work is finished
IPC is worker-initiated only. The dispatcher cannot send unsolicited messages to workers. To add context to a running worker, append notes to the plan file instead.

​
System Flow

Here’s how a typical dispatch flows from command to completion: 
User types: /dispatch "build auth system"
         |
         v
Claude Code (dispatcher session)
  |
  |- Routes request: config? → edit config inline, done
  |                  task?   → continue below
  |
  |- Reads ~/.dispatch/config.yaml (or runs first-run setup)
  |- Creates plan file (.dispatch/tasks/<id>/plan.md) with checklist
  |- Creates IPC directory (.dispatch/tasks/<id>/ipc/)
  |- Resolves model → backend → command
  |- Writes wrapper script, spawns worker as background task
  |- Writes monitor script, spawns monitor as background task
  |- Returns control to user immediately
  |
  v
Worker checks off items in plan.md as it completes them
  |
  |- All items done? → writes ipc/.done → monitor exits
  |
  |- Hit a blocker? → writes ipc/001.question → monitor exits
  |                    ↓
  |    <task-notification> triggers
  |                    ↓
  |    Dispatcher reads question, asks user
  |                    ↓
  |    User answers → dispatcher writes ipc/001.answer
  |                    ↓
  |    Dispatcher respawns monitor
  |                    ↓
  |    Worker detects answer, writes 001.done, continues
  |
  |- Timeout (no answer in ~3 min)?
  |    → Worker dumps context.md, marks item [?], exits
  |
  v
Dispatcher reads plan.md to track progress
  |
  |- Reports completion, blocked items, or errors to user

​
Directory Structure

All dispatch state lives in the .dispatch/ directory: 
.dispatch/
  tasks/
    <task-id>/
      plan.md      # Checklist updated by worker as it progresses
      output.md    # Final output artifact (report, summary, etc.)
      context.md   # Worker context dump on IPC timeout (optional)
      ipc/         # Bidirectional IPC files
        001.question  # Worker's question (plain text)
        001.answer    # Dispatcher's answer (plain text)
        001.done      # Worker's acknowledgment
        .done         # Completion marker when all tasks finish
The .dispatch/ directory is ephemeral. Delete it anytime to clean up task state.

​
Worker and Dispatcher Interaction

​
Dispatching a Task

  1. Dispatcher reads config to determine which model/backend to use
  2. Dispatcher writes a plan file with concrete, verifiable checklist items
  3. Dispatcher creates scaffolding (IPC dir, prompt file, wrapper scripts) in a single bash call
  4. Dispatcher spawns worker and monitor as background processes
  5. Dispatcher returns control to user immediately

​
During Execution

  • Worker reads the plan file and works through items sequentially
  • Worker updates plan file after completing each item ([ ] → [x])
  • Monitor polls the IPC directory for questions or completion markers
  • Dispatcher can check progress anytime by reading the plan file

​
When Worker Needs Help

  1. Worker writes a question file (e.g., 001.question) using atomic write pattern
  2. Monitor detects unanswered question and exits, triggering notification
  3. Dispatcher reads question and surfaces it to user
  4. User provides answer
  5. Dispatcher writes answer file (001.answer) atomically
  6. Dispatcher respawns monitor
  7. Worker detects answer, writes acknowledgment (001.done), continues working
This flow preserves the worker’s full context - no need to spawn a new agent or re-explain the task.

​
On Completion

  • Worker writes .done marker to IPC directory
  • Monitor detects .done and exits cleanly
  • Notification triggers dispatcher to read final plan state
  • Dispatcher reports results to user

​
Key Design Patterns

The plan file IS the progress tracker. No separate status files or polling needed. The dispatcher simply reads the plan to see what’s done, pending, blocked, or errored.
Each worker gets its own instance with a clean prompt. No context bleeding between tasks. This enables true parallel execution.
The dispatcher returns control immediately after spawning workers. You can continue working while tasks run in the background. Progress arrives via <task-notification> events.
All IPC file writes use a two-step pattern (write .tmp → mv) to prevent reading partial data. This ensures reliability even with concurrent access.
The host session (where you type /dispatch) must be Claude Code - it’s the only environment that runs the dispatcher skill. Workers can be any CLI that accepts a prompt (Claude Code, Cursor, Codex).
Workers launch through wrapper scripts (/tmp/worker--<task-id>.sh) so Claude Code’s status bar shows human-readable labels instead of raw CLI commands.
When a worker fails to start (auth error, quota exceeded, CLI unavailable), the dispatcher checks which CLIs are available and offers alternatives from your config, updating the default if needed.

​
Configuration System

Dispatch uses ~/.dispatch/config.yaml to manage models and backends: 
default: opus  # Your 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 models (use stable aliases)
  opus:   { backend: claude }
  sonnet: { backend: claude }
  haiku:  { backend: claude }
  
  # OpenAI models
  gpt-5.3-codex: { backend: codex }
  
aliases:
  security-reviewer:
    model: opus
    prompt: >
      You are a security-focused reviewer. Prioritize OWASP Top 10
      vulnerabilities, auth flaws, and injection risks.
On first run, Dispatch auto-detects available CLIs and models, then generates this config file for you.

​
Next Steps

How It Works

Dive deeper into the step-by-step execution flow

IPC Protocol

Learn about the communication protocol between dispatcher and workers

Build docs developers (and LLMs) love

Get started for freeTalk to us