Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Why Parallelize?

Sequential execution wastes time when tasks are independent:
ApproachExecutionTime
SequentialTask1 → Task2 → Task3 → Task44 hours
ParallelTask1 + Task2 + Task3 + Task4 (concurrent)1 hour

​
When to Parallelize

​
Good Candidates

  • Independent research tasks
  • Multiple file analyses
  • Different codebase sections
  • Separate feature implementations
  • Parallel test suites

​
Poor Candidates

  • Tasks with dependencies
  • Shared resource modifications
  • Sequential workflows
  • Tasks requiring prior results

​
Parallelization Patterns

Use separate worktrees to avoid branch conflicts: 
# Create isolated worktree per agent
git worktree add ../.worktrees/issue-1 -b solve/issue-1 origin/main
git worktree add ../.worktrees/issue-2 -b solve/issue-2 origin/main

# Agents work in parallel
cd ../.worktrees/issue-1 && claude "Fix issue 1"
cd ../.worktrees/issue-2 && claude "Fix issue 2"

# Cleanup after PRs created
git worktree remove ../.worktrees/issue-1 --force
git worktree remove ../.worktrees/issue-2 --force

​
2. Task Tool Parallelization

Spawn multiple agents in a single message: 
// Bad: Sequential
await Task({ prompt: "Research A" });
await Task({ prompt: "Research B" });

// Good: Parallel (multiple tool calls in one message)
Task({ prompt: "Research A" })
Task({ prompt: "Research B" })

​
3. Domain Separation

Assign agents to non-overlapping domains:
Orchestrator delegates to:

Auth Agent

src/auth/

API Agent

src/api/

UI Agent

src/ui/

​
4. Map-Reduce

Parallel processing with aggregation:
1

Input

Files: [file1, file2, file3, file4]
2

Map (parallel)

Haiku processes [f1, f2] | Haiku processes [f3, f4]
3

Reduce

Sonnet synthesizes all results into final output

​
Implementation

​
Worktree Script

#!/bin/bash
# parallel-solve.sh

issues=("$@")
pids=()

for issue in "${issues[@]}"; do
  (
    worktree="../.worktrees/issue-${issue}"
    git worktree add "$worktree" -b "solve/issue-${issue}" origin/main
    cd "$worktree"
    claude --print "Solve issue #${issue}"
    gh pr create --title "Fix #${issue}" --body "Automated fix"
    cd -
    git worktree remove "$worktree" --force
  ) &
  pids+=($!)
done

# Wait for all
for pid in "${pids[@]}"; do
  wait $pid
done

​
Squad Parallel Execution

# SQUAD.md
## Parallel Agents

### researcher-1
Investigates competitor A

### researcher-2
Investigates competitor B

### researcher-3
Investigates competitor C

## Orchestration
Run all researchers in parallel, then synthesize results.

​
Claude Code Parallel Tasks

// Launch multiple agents concurrently
const results = await Promise.all([
  Task({ prompt: "Analyze frontend performance" }),
  Task({ prompt: "Analyze backend performance" }),
  Task({ prompt: "Analyze database queries" })
]);

// Synthesize results
const synthesis = await Task({
  prompt: `Synthesize these findings: ${JSON.stringify(results)}`
});

​
Coordination Strategies

​
Shared Context File

# .agents/parallel-context.md

## Task Status
- [ ] Auth module - Agent 1
- [ ] API module - Agent 2
- [x] UI module - Agent 3 (complete)

## Findings
### UI Module (Agent 3)
- Found 3 accessibility issues
- Performance bottleneck in table component

​
Lock Files for Shared Resources

# Before modifying shared file
while [ -f .lock ]; do sleep 1; done
touch .lock

# Do work...

# Release lock
rm .lock

​
Dependency Declaration

# task-manifest.yaml
tasks:
  - id: setup-db
    parallel: false

  - id: backend
    depends_on: [setup-db]
    parallel: true

  - id: frontend
    depends_on: [setup-db]
    parallel: true

  - id: integration-tests
    depends_on: [backend, frontend]
    parallel: false

​
Resource Management

​
Limit Concurrent Agents

# Max 3 parallel agents
MAX_PARALLEL=3

for task in "${tasks[@]}"; do
  while [ $(jobs -r | wc -l) -ge $MAX_PARALLEL ]; do
    sleep 1
  done
  run_agent "$task" &
done

wait

​
Token Budget Distribution

const TOTAL_BUDGET = 100000;  // tokens
const agents = 4;
const perAgentBudget = TOTAL_BUDGET / agents;

agents.forEach(agent => {
  agent.maxTokens = perAgentBudget;
});

​
Monitoring Parallel Execution

​
Status Dashboard

# Watch worktree status
watch -n 5 'for w in ../.worktrees/*; do
  echo "=== $(basename $w) ==="
  git -C $w status --short
done'

​
Aggregate Logs

# Tail all agent logs
tail -f ../.worktrees/*/agent.log

​
Best Practices

  • Use git worktrees for code-modifying agents
  • Limit parallelism to available resources
  • Declare dependencies explicitly
  • Monitor all parallel processes
  • Use locks for shared resources
  • Aggregate results after completion
Common issues:
  • Branch conflicts (solve with worktrees)
  • Resource contention (use locks)
  • Orphaned processes (track PIDs)
  • Memory exhaustion (limit concurrency)
  • Inconsistent state (use transactions)

Multi-LLM Usage

Assign different models to parallel tasks

Token Economics

Budget tokens across parallel agents