Skip to main content
This guide gets you from zero to dispatching your first background task.
Already installed? Skip to Your First Dispatch

​
Installation

Install Dispatch as a Claude Code skill: 
npx skills add bassimeledath/dispatch -g
On first use, Dispatch will auto-configure itself. Let’s trigger that now.

​
Your First Dispatch

1

Run a simple dispatch command

In Claude Code, run:
/dispatch use sonnet to count how many TypeScript files are in this project
If this is your first dispatch, setup runs automatically. Choose opus or sonnet as your default when prompted.
2

Dispatch creates a plan and spawns a worker

You’ll see output like:
Dispatched count-ts-files using sonnet. Plan:
  1. Find all .ts and .tsx files
  2. Count them
  3. Write summary to output.md

What else?
Your session is immediately free. The worker runs in the background.
3

Check progress (optional)

At any time, ask:
status
You’ll see the checklist with progress:
count-ts-files progress:
  [x] Find all .ts and .tsx files
  [x] Count them
  [ ] Write summary to output.md
4

Wait for completion

When the worker finishes, the dispatcher reports:
count-ts-files complete. Found 47 TypeScript files.
Full report at .dispatch/tasks/count-ts-files/output.md

​
Understanding the Output

Dispatch creates a task directory at .dispatch/tasks/<task-id>/: 
.dispatch/tasks/count-ts-files/
  plan.md      # Checklist updated as worker progresses
  output.md    # Final report/summary
  ipc/         # Question/answer communication (if needed)

cat .dispatch/tasks/count-ts-files/plan.md
Output:
# Count TypeScript Files

- [x] Find all .ts and .tsx files
- [x] Count them
- [x] Write summary to output.md
The [x] markers show completed items. The worker updates this file as it works.
cat .dispatch/tasks/count-ts-files/output.md
Output:
# TypeScript File Count

Found 47 TypeScript files:
- 32 .ts files
- 15 .tsx files

Largest files:
- src/components/Dashboard.tsx (450 lines)
- src/lib/api.ts (380 lines)
- src/pages/index.tsx (320 lines)

​
Handling Questions

Workers can ask clarifying questions without losing context. Let’s try: 
/dispatch implement the feature described in requirements.txt
If requirements.txt doesn’t exist, the worker asks: 
Worker is asking: "requirements.txt doesn't exist. What feature should I implement?"
You answer: 
Add a /health endpoint that returns JSON with uptime and version.
The dispatcher relays your answer, and the worker continues—no restart, no context lost: 
Answer sent. Worker is continuing.

​
Using Different Models

Dispatch supports multiple models. Specify the model in your prompt: 
/dispatch use opus to review this PR for edge cases
If you don’t specify a model, Dispatch uses your default (set during first-run setup).

​
Parallel Dispatch

Dispatch multiple tasks simultaneously: 
/dispatch we need three things done:

1) use sonnet to add error handling to the API endpoints
2) use opus to review the auth flow for security issues
3) use gemini to generate API documentation

all three can run in parallel
All three workers start immediately. Your session stays lean. Results arrive as they complete.

​
Common Patterns

/dispatch use opus to do a security audit of the auth module

/dispatch use sonnet to refactor the database layer to use Prisma

/dispatch use sonnet to write unit tests for src/lib/utils.ts

/dispatch use gemini to update the README with the new API endpoints

/dispatch use sonnet to fix the login redirect bug in src/auth.ts

​
Checking Status

At any time, ask for status: 
status
Dispatch shows progress for all active tasks: 
Active tasks:

● security-audit (opus):
  [x] Scan for hardcoded secrets
  [x] Review authentication logic
  [ ] Check dependencies for known vulnerabilities
  [ ] Write findings report

● add-tests (sonnet):
  [x] Analyze utils.ts functions
  [ ] Write test cases
  [ ] Run tests to verify coverage

​
Next Steps

Configuration

Learn about backends, models, and aliases

Parallel Tasks

Concurrent execution patterns

Architecture

How Dispatch works under the hood

Examples

Real-world dispatch workflows

​
Cleanup

The .dispatch/ directory contains all task files. Delete it to clean up: 
rm -rf .dispatch
Task files are ephemeral—they exist for debugging and reference, but aren’t required for Dispatch to work.

Build docs developers (and LLMs) love

Get started for freeTalk to us