Skip to main content
This guide walks through exactly what happens when you dispatch a task, how state is managed, and how background execution works.

​
Command to Completion Flow

​
Step 1: User Invokes Dispatch

You type a dispatch command in Claude Code: 
/dispatch "review the security of this auth module"
The dispatcher skill activates and routes the request.

​
Step 2: Request Routing

The dispatcher first determines what type of request this is:
Anything that involves actual work:
  • “build a feature”
  • “review this code”
  • “fix the bug in login.ts”
→ Proceeds to task dispatch flow (Steps 3-9)
The dispatcher never handles task requests inline. Even simple tasks get dispatched to background workers. This ensures non-blocking execution.

​
Step 3: Read Configuration

The dispatcher reads ~/.dispatch/config.yaml to determine:
  • Which model to use (from explicit mention in prompt, or the default)
  • Which backend CLI to use (claude, cursor, or codex)
  • How to construct the worker command
First-run setup: If the config doesn’t exist, Dispatch auto-detects available CLIs, discovers models, asks you to choose a default, and generates the config file. 
default: opus  # Default model when none specified

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

models:
  opus:          { backend: claude }
  sonnet:        { backend: claude }
  gpt-5.3-codex: { backend: cursor }

​
Step 4: Create Plan File

The dispatcher analyzes the task and creates a checklist-based plan at .dispatch/tasks/<task-id>/plan.md: 
# Security Review - Auth Module

- [ ] Scan for hardcoded secrets and credentials
- [ ] Review authentication logic in auth.ts
- [ ] Check session management and token handling
- [ ] Audit authorization checks
- [ ] Test for common vulnerabilities (injection, XSS, etc.)
- [ ] Write findings to .dispatch/tasks/security-review/output.md
Plan size matches task complexity. Simple edits get 1-2 items. Complex investigations get 5-8. Each item should be concrete and verifiable.

​
Step 5: Set Up Scaffolding

In a single Bash call, the dispatcher creates all supporting infrastructure:
  1. IPC directory: .dispatch/tasks/<task-id>/ipc/
  2. Worker prompt file: /tmp/dispatch-<task-id>-prompt.txt
  3. Worker wrapper script: /tmp/worker--<task-id>.sh
  4. Monitor script: /tmp/monitor--<task-id>.sh
  5. Permissions: chmod +x on both scripts
# Single atomic operation to set up everything
mkdir -p .dispatch/tasks/security-review/ipc

cat > /tmp/dispatch-security-review-prompt.txt << 'PROMPT'
You have a plan file at .dispatch/tasks/security-review/plan.md containing a checklist.
Work through it top to bottom. For each item, do the work, update the plan file ([ ] → [x]), and move to the next.

If you need to ask the user a question, write it to .dispatch/tasks/security-review/ipc/<NNN>.question (atomic write via temp file + mv; sequence from 001). Poll for a matching .answer file. When you receive the answer, write a .done marker and continue.

When all items are checked, write: touch .dispatch/tasks/security-review/ipc/.done

Context:
- Review the authentication module in src/auth/
- Focus on common vulnerabilities: hardcoded secrets, weak session management, injection risks
- Write detailed findings with file:line references
PROMPT

cat > /tmp/worker--security-review.sh << 'WORKER'
#!/bin/bash
env -u CLAUDE_CODE_ENTRYPOINT -u CLAUDECODE \
  claude -p --dangerously-skip-permissions \
  "$(cat /tmp/dispatch-security-review-prompt.txt)" 2>&1
WORKER

cat > /tmp/monitor--security-review.sh << 'MONITOR'
#!/bin/bash
IPC_DIR=".dispatch/tasks/security-review/ipc"
TIMEOUT=1800  # 30 minutes
START=$(date +%s)
shopt -s nullglob

while true; do
  # Exit if task is complete
  [ -f "$IPC_DIR/.done" ] && exit 0
  
  # Exit if unanswered question found
  for q in "$IPC_DIR"/*.question; do
    seq=$(basename "$q" .question)
    [ ! -f "$IPC_DIR/${seq}.answer" ] && exit 0
  done
  
  # Exit if timeout exceeded
  ELAPSED=$(( $(date +%s) - START ))
  [ "$ELAPSED" -ge "$TIMEOUT" ] && exit 1
  
  sleep 3
done
MONITOR

chmod +x /tmp/worker--security-review.sh /tmp/monitor--security-review.sh

​
Step 6: Spawn Worker and Monitor

The dispatcher launches both processes as background tasks: 
# Worker process - does the actual work
bash /tmp/worker--security-review.sh
# description: "Run dispatch worker: security-review"

# Monitor process - watches for questions and completion
bash /tmp/monitor--security-review.sh
# description: "Monitoring progress: security-review"
Both run in the background. The dispatcher records their task IDs internally but does not show them to the user (implementation detail).

​
Step 7: Report and Return Control

The dispatcher immediately reports back and returns control: 
Dispatched `security-review` using opus. Plan:
  1. Scan for hardcoded secrets and credentials
  2. Review authentication logic in auth.ts
  3. Check session management and token handling
  4. Audit authorization checks
  5. Test for common vulnerabilities
  6. Write findings report

What else?
You can continue working - the task runs in the background.

​
Step 8: Worker Executes

The worker agent:
  1. Reads .dispatch/tasks/security-review/plan.md
  2. Works through items sequentially
  3. Updates the plan file after each item: 
    - [x] Scan for hardcoded secrets and credentials
- [x] Review authentication logic in auth.ts
- [ ] Check session management and token handling
- [ ] Audit authorization checks
- [ ] Test for common vulnerabilities
- [ ] Write findings report
  4. If blocked, writes a question file (see IPC Protocol)
  5. When all items are checked, writes .dispatch/tasks/security-review/ipc/.done
Meanwhile, the monitor polls every 3 seconds for questions or the completion marker.

​
Step 9: Completion or Notification

  1. Worker writes .done marker
  2. Monitor detects it and exits cleanly
  3. <task-notification> triggers
  4. Dispatcher reads the final plan state
  5. Dispatcher reports results:
`security-review` complete. Found 3 issues:
  1. Hardcoded API key in auth.ts:47
  2. Weak session timeout (24 hours)
  3. No rate limiting on /login endpoint

Full report at .dispatch/tasks/security-review/output.md

​
Checklist-Based State Management

The plan file is the single source of truth for task state. No separate status files, databases, or polling APIs needed.

​
State Markers

MarkerMeaningExample
[ ]Pending or in progress- [ ] Review auth logic
[x]Completed- [x] Scan for secrets
[?]Blocked (needs user input)- [?] Review auth.ts or legacy-auth.ts?
[!]Error encountered- [!] Cannot access database credentials

​
Reading State

The dispatcher checks progress by simply reading the plan file: 
cat .dispatch/tasks/security-review/plan.md

# Security Review

- [x] Scan for hardcoded secrets
- [x] Review authentication logic
- [x] Check session management
- [x] Write findings report

​
Adding Context Mid-Flight

If you remember something important while a task is running, append it to the plan file: 
# Security Review

- [x] Scan for hardcoded secrets
- [ ] Review authentication logic
- [ ] Check session management
- [ ] Write findings report

> **Note from dispatcher:** The admin panel uses legacy-auth.js, not auth.ts. Make sure to check both.
The worker reads the plan file as it progresses, so it will see your note before reaching later items.
Do NOT write to the IPC directory to send messages to workers. IPC is worker-initiated only. Unsolicited files in ipc/ will be ignored.

​
Background Execution Model

​
Why Background?

Without background execution, you’d be blocked waiting for potentially long-running tasks: 
You: "Review security across the entire codebase"
Claude: *spends 10 minutes reading files, analyzing code*
         *you can't do anything else during this time*
Claude: "Found 12 issues..."  ← finally
With Dispatch: 
You: /dispatch "Review security across the entire codebase"
Dispatch: Dispatched `security-review` using opus. [plan summary]
You: *continue working on other things*

[10 minutes later]
<task-notification>
Dispatch: `security-review` complete. Found 12 issues...

​
How It Works

  1. Worker runs as a background process - separate from your active Claude Code session
  2. Monitor runs as a background process - polls IPC directory, triggers notifications
  3. You retain control - can continue working, check progress anytime, dispatch more tasks
  4. Notifications bring you back - when the worker needs help or finishes

​
Checking Progress Anytime

You don’t need to wait for notifications. Ask anytime: 
You: "Check the status of security-review"
Dispatch: [reads plan.md]
         3/6 items complete:
           ✓ Scan for hardcoded secrets
           ✓ Review authentication logic
           ✓ Check session management
           • Auditing authorization checks...

​
Multiple Parallel Tasks

Dispatch multiple independent tasks simultaneously: 
/dispatch "review security" 
/dispatch "update all dependencies"
/dispatch "write API documentation"
Each gets its own:
  • Plan file (.dispatch/tasks/security-review/plan.md, etc.)
  • Worker process
  • Monitor process
  • IPC directory
All run in parallel. Notifications arrive independently as each completes or needs help.

​
Monitor Detection and Notifications

​
The Monitor Script

Each task has a lightweight monitor script that: 
# Polls every 3 seconds
while true; do
  # Exit if task is complete
  [ -f "$IPC_DIR/.done" ] && exit 0
  
  # Exit if unanswered question found
  for q in "$IPC_DIR"/*.question; do
    seq=$(basename "$q" .question)
    [ ! -f "$IPC_DIR/${seq}.answer" ] && exit 0
  done
  
  # Exit if timeout exceeded (30 min)
  [ "$ELAPSED" -ge "$TIMEOUT" ] && exit 1
  
  sleep 3
done

​
What Triggers Notifications

  1. Worker writes .dispatch/tasks/<task-id>/ipc/.done
  2. Monitor detects .done on next poll
  3. Monitor exits with code 0 (success)
  4. <task-notification> fires
  5. Dispatcher reads final plan state
  6. Dispatcher reports completion to you
  1. Worker writes 001.question (or next sequence number)
  2. Monitor detects unanswered question on next poll
  3. Monitor exits with code 0
  4. <task-notification> fires
  5. Dispatcher reads question file
  6. Dispatcher surfaces question to you
  7. You provide answer
  8. Dispatcher writes answer file, respawns monitor
  1. Worker process exits (error, crash, or manual kill)
  2. Worker’s background task terminates
  3. <task-notification> fires for worker task ID
  4. Dispatcher reads plan state
  5. Dispatcher reports which items completed, which didn’t
  6. Dispatcher offers to retry or investigate
  1. No activity (no questions, no completion) for 30 minutes
  2. Monitor exits with code 1 (error)
  3. <task-notification> fires
  4. Dispatcher checks if worker is still running
  5. Dispatcher reports timeout, reads plan state

​
Why Two Processes?

Why not have the worker exit when it has a question?

Context Preservation

If the worker exits, it loses all in-memory context:
  • Files it has read
  • Code analysis it has performed
  • Intermediate results
  • Understanding of the codebase structure
By staying alive and waiting for an answer, the worker preserves this context and can continue immediately once you respond.
The monitor is a lightweight “watcher” that triggers notifications without interrupting the worker’s execution.

​
Fallback Behavior

If the worker waits too long for an answer (~3 minutes):
  1. Worker dumps its context to .dispatch/tasks/<task-id>/context.md
  2. Worker marks the item [?] with the question inline in plan.md
  3. Worker exits
  4. When you provide an answer, dispatcher spawns a new worker with:
    • The original plan
    • Context from context.md
    • Your answer
This prevents indefinite waiting, but means losing the in-memory context (why the 3-minute window exists for IPC).

​
Next Steps

Architecture

Understand the components and system design

IPC Protocol

Learn the technical details of worker-dispatcher communication

Build docs developers (and LLMs) love

Get started for freeTalk to us