Parallel Agent Execution

Sequential vs Parallel

By default, agents run one at a time. Agent A finishes, then Agent B starts. This is safe and simple, but slow. A 4-step workflow that takes 2 minutes per step finishes in 8 minutes sequentially. If those steps are independent, running them in parallel finishes in 2 minutes.

Sequential wins when steps have data dependencies — step B needs the output of step A. Parallel wins when steps are independent — writing tests, updating docs, and linting code can all happen at the same time because none depends on the others.

The Agent Tool with run_in_background

Claude Code's Agent tool supports a run_in_background parameter. When set to true, the agent spawns and returns immediately — you do not wait for its result. This is the foundation of parallel execution:

• Spawn: Launch multiple agents with run_in_background: true
• Continue: The orchestrator keeps working while background agents execute
• Collect: Read results when background agents complete (you get notified)

The key insight: you do not poll or sleep. The system notifies you when each agent finishes. This is event-driven, not polling-driven.

Task Independence Analysis

Before parallelizing, you must determine which tasks are truly independent. Ask three questions about any pair of tasks:

• Data dependency: Does Task B need the output of Task A? If yes, they must be sequential
• Resource conflict: Do both tasks modify the same file? If yes, they need coordination
• Order sensitivity: Does the final result change if you swap the execution order? If yes, enforce ordering

A dependency graph helps. Draw tasks as nodes and dependencies as arrows. Tasks with no incoming arrows from other pending tasks can run in parallel.

Merging Results

Parallel agents produce separate outputs that must be combined. The merge strategy depends on the output type:

• Additive: Each agent writes to a different file. No merge needed — just collect all files
• Aggregative: Each agent produces a partial answer (e.g., test results). Concatenate or summarize
• Competitive: Multiple agents attempt the same task. Pick the best result by quality score
• Consensus: Multiple agents vote on a decision. Use majority or weighted voting

Design your workflow so agents write to separate files whenever possible. The additive pattern is the simplest and most reliable merge strategy.

Race Conditions and Conflicts

The most common failure in parallel execution is two agents editing the same file simultaneously. This creates git merge conflicts or, worse, silent data corruption where one agent's changes overwrite another's.

• File locking: Assign each agent exclusive ownership of specific files. No two agents touch the same file
• Sequential merge phase: Agents write to temporary files, then a single merge agent combines them
• Conflict detection: After parallel execution, run git diff to detect overlapping changes and resolve manually

Prevention is cheaper than resolution. Spend time upfront splitting work so agents operate on non-overlapping file sets.

Resource Limits

More agents is not always better. Each concurrent agent consumes resources:

• Context window budget: Each agent uses its own context window. 4 parallel agents consume 4x the tokens
• API rate limits: Most providers cap concurrent requests. Exceeding limits causes throttling or errors
• Coordination overhead: More agents means more results to merge and more potential conflicts
• Diminishing returns: Beyond 6-8 parallel agents, the coordination cost often exceeds the time savings

Start with 2-3 parallel agents. Measure the wall-clock speedup. Only add more if the bottleneck is execution time, not coordination.

Practical Exercise

Take a 4-step sequential workflow and parallelize it. The workflow: (1) write unit tests, (2) update API documentation, (3) run a linter, (4) generate a changelog entry. Steps 1-3 are independent. Step 4 depends on step 1 (it references test coverage).

• Draw the dependency graph — identify which steps can run in parallel
• Spawn steps 1, 2, and 3 as background agents simultaneously
• Wait for step 1 to complete, then spawn step 4 with its output
• Measure total wall-clock time vs running all 4 steps sequentially
• Verify no file conflicts occurred between the parallel agents

You should see roughly a 3x speedup on the parallel portion. The sequential step 4 adds a fixed cost that cannot be parallelized — this is Amdahl's Law in practice.