Parallel Agent Orchestration

When launching multiple agents in parallel, follow this pattern to avoid context bloat.

Core Principles

1. •No TaskOutput calls - TaskOutput returns full agent output, bloating context
2. •Run in background - Always use run_in_background: true
3. •File-based confirmation - Agents write status to files, not return values
4. •Append, don't overwrite - Multiple agents can write to same status file

Output Patterns

Simple Confirmation (parallel batch work)

For tasks where agents just need to confirm completion:

# Agent writes to shared status file
echo "COMPLETE: <task-name> - $(date)" >> .claude/cache/<batch-name>-status.txt

• •Use >> to append (not > which overwrites)
• •Include timestamp for ordering
• •One line per agent completion
• •Check with: cat .claude/cache/<batch-name>-status.txt

Detailed Output (research/exploration)

For tasks requiring detailed findings:

.claude/cache/agents/<task-type>/<agent-id>/
├── output.md      # Main findings
├── artifacts/     # Any generated files
└── status.txt     # Completion confirmation

• •Each agent gets own directory
• •Full output preserved for later reading
• •Status file still used for quick completion check

Task Prompt Template

# Task: <TASK_NAME>

## Your Mission
<clear objective>

## Output
When done, write confirmation:
\`\`\`bash
echo "COMPLETE: <identifier> - $(date)" >> .claude/cache/<batch>-status.txt
\`\`\`

Do NOT return large output. Complete work silently.

Launching Pattern

// Launch all in single message block (parallel)
Task({
  description: "Task 1",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
Task({
  description: "Task 2",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
// ... up to 15 parallel agents

Monitoring

# Check completion status
cat .claude/cache/<batch>-status.txt

# Count completions
wc -l .claude/cache/<batch>-status.txt

# Watch for updates
tail -f .claude/cache/<batch>-status.txt

Batch Size

• •Max 15 agents per parallel batch
• •Wait for batch to complete before launching next
• •Use status file to track which completed

DO

• •Use run_in_background: true always
• •Have agents write to status files
• •Use append (>>) not overwrite (>)
• •Give each agent clear, self-contained instructions
• •Include all context in prompt (agents don't share memory)

DON'T

• •Call TaskOutput (bloats context)
• •Return large outputs from agents
• •Launch more than 15 at once
• •Rely on agent return values for orchestration

Example: Provider Backfill

# Status file
.claude/cache/provider-backfill-status.txt

# Each agent appends on completion
echo "COMPLETE: anthropic - Thu Jan 2 12:34:56 2025" >> .claude/cache/provider-backfill-status.txt
echo "COMPLETE: openai - Thu Jan 2 12:35:12 2025" >> .claude/cache/provider-backfill-status.txt

Check progress:

cat .claude/cache/provider-backfill-status.txt
# COMPLETE: anthropic - Thu Jan 2 12:34:56 2025
# COMPLETE: openai - Thu Jan 2 12:35:12 2025