Parallel Agent Orchestration
When launching multiple agents in parallel, follow this pattern to avoid context bloat.
Core Principles
-
No TaskOutput calls - TaskOutput returns full agent output, bloating context
-
Run in background - Always use run_in_background: true
-
File-based confirmation - Agents write status to files, not return values
-
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