Quickstart

Get to a working Dispatch example in under 5 minutes

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)

View the plan file

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.

View the output

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:

Claude Opus

/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

Security review

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

Refactoring

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

Testing

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

Documentation

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

Bug fixes

/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.