Parallel Agents

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 fileecho "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>
## OutputWhen done, write confirmation:\`\`\`bashecho "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 statuscat .claude/cache/<batch>-status.txt
# Count completionswc -l .claude/cache/<batch>-status.txt
# Watch for updatestail -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 completionecho "COMPLETE: anthropic - Thu Jan 2 12:34:56 2025" >> .claude/cache/provider-backfill-status.txtecho "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