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:

```bash
# 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

```markdown
# 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

```typescript
// 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

```bash
# 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

```bash
# 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:
```bash
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
```