Dispatch Bible

Dispatch Bible

Dispatch is Claude's system for executing tasks in the background -- detached from the interactive session. Instead of blocking the conversation while a long build runs, Dispatch queues the work, executes it asynchronously, and notifies you when it finishes. This skill covers Bible-optimized patterns for making Dispatch reliable, cost-efficient, and integrated with the rest of your workflow.

What Dispatch Is

Dispatch runs Claude Code in headless mode (--headless) as a background process. The session operates without interactive input, follows a task description, and writes results to disk. Key properties:

• Non-blocking -- your interactive session stays free
• Crash-recoverable -- checkpoint files survive process death
• Cost-bounded -- --max-turns prevents infinite loops
• Composable -- chain multiple Dispatch tasks into pipelines

When to Use Dispatch

When NOT to Use Dispatch

• Tasks requiring human judgment mid-execution
• Problems where you don't know the root cause yet
• Work that modifies shared state (risk of conflicts with interactive session)
• Anything requiring interactive prompts or confirmation

Architecture

Execution Model

Interactive Session                  Dispatch Worker
      |                                    |
      |-- queue task ------------------>   |
      |                                    |-- read task description
      |   (session continues)              |-- load CLAUDE.md context
      |                                    |-- execute with --max-turns
      |                                    |-- write checkpoint after each step
      |                                    |-- write results to output/
      |   <-- notification (complete) --   |
      |                                    |
      |-- read results                     |

File Layout

project/
  tasks/
    dispatch-queue.json       # Pending tasks
    checkpoint.json           # Current execution state
    dispatch-history.json     # Completed task log
  output/
    dispatch/                 # Task outputs
      {task-id}/              # Per-task output directory
        result.json           # Structured result
        log.txt               # Execution log
        artifacts/            # Generated files
  .claude/
    settings.json             # Permissions for headless mode

Bible-Optimized Dispatch Extensions

1. Task Commander Integration

Dispatch tasks reference tasks/todo.md for structured execution:

claude --headless --max-turns 50 \
  "Read tasks/todo.md. Execute all items marked 'dispatch'. For each:
   1. Mark as in-progress
   2. Execute the task
   3. Write result to output/dispatch/{task-id}/
   4. Mark as done in todo.md
   5. Update tasks/checkpoint.json
   If a task fails, mark it as blocked with the error and continue to the next."

The Task Commander pattern ensures:

• Progress is visible in tasks/todo.md
• Other sessions can see what Dispatch is working on
• Blocked items get human attention on next interactive session

2. Mode-Aware Execution

Dispatch respects the current Bible mode:

Set mode in the task description:

claude --headless --max-turns 100 \
  "Mode: night. Follow overnight-runner patterns.
   Read tasks/batch-queue.json and process all items.
   Budget: up to $5.00. Retry on rate limits (30min backoff, 5 attempts max)."

3. Skill Chaining

Dispatch tasks can reference CC Commander skills for structured execution:

claude --headless --max-turns 30 \
  "Execute in order:
   1. Run verification-loop skill on src/
   2. Run coding-standards skill on changed files
   3. Run security check (pentest-checklist skill) on auth modules
   4. Write combined report to output/dispatch/quality-gate/result.md"

Background Task Patterns

Overnight Builds

#!/bin/bash
# overnight-build.sh -- run via cron at 1:00 AM

PROJECT="/path/to/project"
LOG="$PROJECT/output/dispatch/builds/$(date +%Y-%m-%d).log"
CHECKPOINT="$PROJECT/tasks/checkpoint.json"

# Initialize checkpoint
cat > "$CHECKPOINT" << 'CHECKPOINT_EOF'
{
  "task": "overnight-build",
  "status": "starting",
  "startedAt": "TIMESTAMP",
  "steps": ["lint", "typecheck", "test", "build", "e2e"],
  "completedSteps": [],
  "errors": []
}
CHECKPOINT_EOF
sed -i '' "s/TIMESTAMP/$(date -u +%Y-%m-%dT%H:%M:%SZ)/" "$CHECKPOINT"

claude --headless --max-turns 80 \
  "Follow the overnight build pipeline. Read tasks/checkpoint.json for state.
   For each step in the pipeline:
   1. Run the step (lint, typecheck, test, build, e2e)
   2. Update checkpoint.json with result
   3. If step fails, log error and continue to next step
   4. Write step output to output/dispatch/builds/steps/{step-name}.log
   On completion, write summary to output/dispatch/builds/$(date +%Y-%m-%d).md
   Set checkpoint status to 'complete' or 'partial' (if any step failed)." \
  2>&1 | tee "$LOG"

# Notify on completion
if command -v terminal-notifier &>/dev/null; then
  STATUS=$(jq -r .status "$CHECKPOINT")
  terminal-notifier -title "Overnight Build" -message "Status: $STATUS"
fi

Batch Processing

Process a list of independent items with crash recovery:

claude --headless --max-turns 200 \
  "Process items from tasks/batch-queue.json.

   For each item where status is 'pending':
   1. Set item status to 'processing'
   2. Execute the item's task (described in item.description)
   3. Write output to output/dispatch/batch/{item.id}.json
   4. Set item status to 'done' with result summary
   5. If error: set status to 'error', log to item.error field, continue

   After all items: write batch summary to output/dispatch/batch/summary.md
   Include: total, completed, errors, duration estimate.

   IMPORTANT: Save tasks/batch-queue.json after EVERY item (crash recovery)."

Queue file format:

{
  "batchId": "dep-update-2026-03-28",
  "items": [
    {
      "id": "item-001",
      "status": "pending",
      "description": "Update @types/node to latest",
      "priority": "medium",
      "error": null,
      "result": null,
      "startedAt": null,
      "completedAt": null
    }
  ],
  "metadata": {
    "createdAt": "2026-03-28T00:00:00Z",
    "totalItems": 50,
    "completedItems": 0,
    "errorItems": 0
  }
}

Scheduled Reviews

Weekly code quality review running every Friday:

# cron: 0 16 * * 5
claude --headless --max-turns 40 \
  "Run weekly code review.
   1. git log --since='1 week ago' --oneline to list recent commits
   2. For each significant commit (skip merge commits, version bumps):
      a. git show {hash} to read the diff
      b. Check against coding-standards skill rules
      c. Flag security issues per pentest-checklist skill
      d. Note missing tests
   3. Write review to output/dispatch/reviews/week-$(date +%Y-%m-%d).md
   4. Format: ## Summary, ## Issues Found (Critical/High/Medium), ## Recommendations"

Dispatch + Task Commander Integration

Bidirectional Flow

Task Commander (tasks/todo.md)
      |
      |-- items marked 'dispatch' --> Dispatch Queue
      |                                     |
      |                                     |-- executes item
      |                                     |
      |<-- updates item status -------------|
      |                                     |
      |-- blocked items --> human review    |

Tagging Convention

In tasks/todo.md, tag items for Dispatch:

## In Progress
- [x] Setup auth module
- [ ] [dispatch] Run full regression suite (overnight)
- [ ] [dispatch:night] Batch process 500 customer records
- [ ] [dispatch:scheduled:0 9 * * 1] Weekly dependency audit

## Blocked
- [ ] [dispatch:blocked] Migration step 3 -- needs schema approval

Tags:

• [dispatch] -- run in next available Dispatch window
• [dispatch:night] -- run in night mode (extended budget)
• [dispatch:scheduled:CRON] -- run on cron schedule
• [dispatch:blocked] -- was dispatched, hit a blocker

Automatic Handoff

When Dispatch encounters a blocker:

1. Mark the task as [dispatch:blocked] in tasks/todo.md
2. Write detailed blocker description to output/dispatch/{task-id}/blocker.md
3. Set tasks/checkpoint.json status to blocked
4. Continue to next dispatchable item (if any)

The next interactive session reads tasks/todo.md, sees blocked items, and handles them.

Error Handling and Retry Patterns

Retry Strategy

#!/bin/bash
# dispatch-with-retry.sh

MAX_RETRIES=5
RETRY_DELAY=1800  # 30 minutes (rate limit recovery)
CHECKPOINT="tasks/checkpoint.json"

for attempt in $(seq 1 $MAX_RETRIES); do
  echo "[$(date)] Dispatch attempt $attempt of $MAX_RETRIES"

  claude --headless --max-turns 100 \
    "Resume from tasks/checkpoint.json. Continue where you left off.
     If you hit a rate limit, save checkpoint and exit gracefully.
     If you hit an error, log it and try the next item." \
    2>&1 | tee -a output/dispatch/retry.log

  EXIT_CODE=$?
  STATUS=$(jq -r .status "$CHECKPOINT" 2>/dev/null || echo "unknown")

  if [ "$STATUS" = "complete" ]; then
    echo "Dispatch completed successfully."
    exit 0
  fi

  if [ "$STATUS" = "blocked" ]; then
    echo "Dispatch blocked -- needs human intervention."
    exit 1
  fi

  if [ "$attempt" -lt "$MAX_RETRIES" ]; then
    echo "Waiting ${RETRY_DELAY}s before retry..."
    sleep $RETRY_DELAY
  fi
done

echo "Max retries reached. Check output/dispatch/retry.log"
exit 2

Error Categories

Graceful Degradation

Dispatch tasks should degrade gracefully:

Task: "Run quality pipeline on all 20 modules.

Priority order: auth, payments, api, (remaining alphabetically).

If you can only complete some modules before hitting limits:
1. Save checkpoint with completed modules
2. Write partial report with what you have
3. Exit cleanly so retry picks up remaining modules

A partial result is better than no result."

Cost Tracking for Background Tasks

Budget Envelope

Every Dispatch task has a cost budget:

{
  "task": "batch-enrichment",
  "budget": {
    "maxDollars": 5.00,
    "alertAtPercent": 80,
    "killAtPercent": 100
  },
  "tracking": {
    "estimatedCostPerItem": 0.02,
    "totalItems": 200,
    "estimatedTotal": 4.00
  }
}

Cost Estimation

Rough cost per operation (for budget planning):

Cost Tracking Script

#!/bin/bash
# Track cost across Dispatch sessions

COST_LOG="output/dispatch/cost-log.json"

# After each Dispatch session, append cost
jq --arg date "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg task "$TASK_NAME" \
   --argjson turns "$TURN_COUNT" \
   '. += [{"date": $date, "task": $task, "turns": $turns, "estimatedCost": ($turns * 0.015)}]' \
   "$COST_LOG" > "$COST_LOG.tmp" && mv "$COST_LOG.tmp" "$COST_LOG"

Notification When Tasks Complete

macOS (terminal-notifier)

STATUS=$(jq -r .status tasks/checkpoint.json)
TASK=$(jq -r .task tasks/checkpoint.json)

terminal-notifier \
  -title "Dispatch: $TASK" \
  -message "Status: $STATUS" \
  -sound "default"

Telegram Bot

BOT_TOKEN="${TELEGRAM_BOT_TOKEN}"
CHAT_ID="${TELEGRAM_CHAT_ID}"
STATUS=$(jq -r .status tasks/checkpoint.json)
TASK=$(jq -r .task tasks/checkpoint.json)
COMPLETED=$(jq -r .completedItems tasks/checkpoint.json)
TOTAL=$(jq -r .totalItems tasks/checkpoint.json)

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
  -d chat_id="${CHAT_ID}" \
  -d parse_mode="Markdown" \
  -d text="*Dispatch Complete*
Task: ${TASK}
Status: ${STATUS}
Progress: ${COMPLETED}/${TOTAL}
Time: $(date)"

Slack Webhook

WEBHOOK_URL="${SLACK_WEBHOOK_URL}"
STATUS=$(jq -r .status tasks/checkpoint.json)

curl -s -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d "{
    \"text\": \"Dispatch task completed\",
    \"blocks\": [{
      \"type\": \"section\",
      \"text\": {
        \"type\": \"mrkdwn\",
        \"text\": \"*Dispatch Complete*\nStatus: ${STATUS}\nSee output/dispatch/ for details.\"
      }
    }]
  }"

File-Based Notification (Simplest)

Write a flag file that your interactive session checks:

# Dispatch writes on completion
echo '{"status":"complete","task":"overnight-build","completedAt":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' \
  > tasks/dispatch-complete.json

# Interactive session checks on startup (in session-startup skill)
if [ -f tasks/dispatch-complete.json ]; then
  echo "[dispatch] Background task completed. Check output/dispatch/ for results."
  cat tasks/dispatch-complete.json
fi

Pre-Flight Checklist

Before launching a Dispatch task:

• tasks/checkpoint.json initialized (or ready for fresh start)
• --max-turns set (prevent infinite loops)
• .claude/settings.json grants all needed permissions for headless mode
• Output directory exists and is writable
• Error handling writes to log files (not just stdout)
• Test with 2-3 items before full batch
• Notification configured (at least file-based)
• Cost budget defined
• No shared state conflicts with interactive sessions
• CLAUDE.md has instructions the Dispatch task needs

Anti-Patterns

Integration with Other CC Commander Skills