parallel-agents

Parallel Agent Orchestration

⭐2.2kstars🔀157forks📁View on GitHub🕐Updated Jan 10, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a robust framework for Parallel Agent Orchestration, enabling the simultaneous execution of up to 15 sub-agents while preventing context bloat. By utilizing background execution and file-based status tracking, it ensures efficient multi-tasking and scalable agentic workflows without overwhelming the primary model's memory.

Use Cases

  • Batch Processing: Executing multiple independent data tasks simultaneously and tracking their progress through a unified status file to save time.
  • Distributed Research: Deploying multiple agents to investigate different topics in parallel, storing detailed findings in organized directory structures for later synthesis.
  • System Backfilling: Performing high-volume updates or data migrations across different providers or databases concurrently to minimize total execution time.
  • Real-time Monitoring: Implementing a centralized logging pattern where background agents report completion status to a shared file for easy observation and progress tracking.
nameparallel-agents
descriptionParallel Agent Orchestration
user-invocablefalse

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