Multi-Agent Coordination — When Subagents Step on Each Other

Claude Code supports up to 10 parallel subagents; Cursor has cloud agents; Codex has codex cloud. Parallel agents are powerful and chaotic. Learn the coordination patterns that work and the failure modes that hurt.

13 min · Reviewed 2026

Ten Agents, One Repo

Spawning multiple agents in parallel is the killer feature of 2026 coding tools. Claude Code can run up to 10 subagents at once. Cursor's cloud agents run in parallel branches. Codex CLI has `codex cloud` for background work. Done well, this collapses a day of work into an hour. Done badly, it's ten agents fighting for the same files.

When parallelism is a clear win

Task	Why parallel works
Codebase exploration	Each agent reads a different module — no overlap
Independent bug fixes	Different files, different test files, different PRs
Test generation across modules	Agents can each tackle one module's tests
Documentation generation	Each subagent documents one feature area
Migration sweeps	Each agent handles one batch of files for the same migration

When parallelism breaks

Two agents editing the same file — last writer wins, lost work
Refactors that touch shared abstractions — types drift across agents
Tasks with sequential dependencies — agent B can't start until A finishes
Anything where global consistency matters more than local progress

The coordination patterns that work

Pattern	How it works	Best for
Branch-per-agent	Each subagent works on its own git branch; merge at end	Independent feature work, parallel bug fixes
Lane-per-agent	Each agent owns specific paths (paths/A/* vs paths/B/*)	Codebase exploration, parallel module work
Producer-consumer	Agent A produces a plan or spec; Agent B implements	Plan-then-execute workflows
Scout-and-builder	Scouts read and summarize; one builder writes code	Large unfamiliar codebases
Reviewer pair	Builder writes; reviewer (different model) audits	Quality-critical features

A real Claude Code subagent setup

# .claude/agents/scout.md
---
name: scout
description: Read-only codebase exploration
tools: [Read, Grep, Glob]   # NO write/edit tools
---
Your job is to explore and summarize. Never edit files.
Return a Markdown report with file:line references.

# .claude/agents/builder.md
---
name: builder
description: Implementation
tools: [Read, Edit, Write, Bash]
---
Implement based on the plan provided. Run tests after each edit.
Never edit files in test/ or migrations/.

# .claude/agents/reviewer.md
---
name: reviewer
description: Read-only PR review
tools: [Read, Bash]
---
Review the diff. List bugs and risks. Never edit.Three subagents with different tool grants. Scout finds, builder builds, reviewer audits. Roles by permission, not by polite request.

Spawning them right

# In Claude Code main session:

"Spawn a scout subagent. Have it explore src/auth/ and write a
Markdown plan for the refactor we discussed. Wait for its report."

# Once the plan exists:

"Spawn a builder subagent for each of the 4 plan steps in parallel,
with each one on its own branch named refactor/auth-step-1 through 4.
Do not start step 2-4 until step 1's branch passes CI."

# Then:

"Spawn a reviewer subagent for each PR. Aggregate the findings into one report."Sequenced parallelism. Some steps fan out, some serialize. The orchestrator (you, or the main session) decides.

Merge conflict survival

Branch-per-agent is the only safe pattern when changes touch shared code
After all agents finish, merge serially — pick the most surgical first, rebase the rest on top
When two agents propose conflicting changes, do not let a third agent resolve it; you do
Use `git rerere` to remember conflict resolutions across rebases
Run the full test suite after each merge, not just at the end

Communication between agents

Subagents in Claude Code don't share memory. They communicate via the orchestrator (the main session) or via files written to disk. A common pattern: each subagent writes a `.claude/scratch/<agent-name>.md` report; the orchestrator reads all of them and synthesizes. Files are the message bus.

When to NOT use multiple agents

Tasks under 30 minutes — coordination overhead exceeds parallelism win
Refactors touching shared types or core abstractions
Anything you wouldn't comfortably hand to multiple junior engineers without coordination
When you don't have CI green on the base branch — agents can't tell what their changes broke

Ten agents in parallel is ten interns who never sleep. Ship the standards, not the code.
— A staff engineer adopting subagents

The big idea: parallel agents are an organizational skill more than a technical one. Pick the coordination pattern that matches the work, scope each agent's tools and paths, branch aggressively, and serialize merges. Done well, you outpace the team. Done poorly, you create the kind of mess one engineer would never make alone.

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-coding-debug-multi-agent-coordination-creators

How many parallel subagents can Claude Code run simultaneously?
1. Up to 10 subagents
2. Up to 20 subagents
3. Up to 5 subagents
4. Unlimited subagents
Which scenario is BEST suited for parallel agent execution?
1. Updating a core abstraction that multiple modules depend on
2. Migrating a database schema that affects all tables
3. Refactoring a shared type used across the entire codebase
4. Running independent bug fixes in different files
Why does parallelism break when two agents edit the same file?
1. Last writer wins and earlier work is lost
2. The file is automatically locked by the system
3. The file becomes corrupted and unreadable
4. The agents get stuck in an infinite loop
What does the 'branch-per-agent' coordination pattern require?
1. Agents share one branch and coordinate through comments
2. Agents must complete work before any branch is created
3. All agents work on the main branch simultaneously
4. Each subagent creates its own git branch and merges at the end
In the 'lane-per-agent' pattern, how is work divided?
1. By time slots—each agent works at a different hour
2. By specific file paths or directory sections
3. By priority level assigned by the orchestrator
4. By model capability—simpler agents get easier lanes
What is the 'producer-consumer' coordination pattern?
1. Agents produce code while humans consume it
2. One agent builds while another watches for errors
3. Agent A creates a plan or spec; Agent B implements it
4. All agents produce output simultaneously for comparison
When is the 'scout-and-builder' pattern most useful?
1. When the codebase is small and well-documented
2. When agents need to test each other's output
3. When all agents need to write code immediately
4. For large, unfamiliar codebases where one agent reads and summarizes before another writes
How do subagents in Claude Code typically communicate with each other?
1. They communicate through code comments in the repository
2. They share direct memory through the orchestrator
3. They write files to disk that other agents can read
4. They send messages through a dedicated chat system
When merging work from multiple branch-per-agent workers, what is the recommended strategy?
1. Let the agents resolve their own conflicts automatically
2. Merge all branches simultaneously in one commit
3. Merge serially, starting with the most surgical changes, then rebase the rest
4. Wait 24 hours before merging to ensure stability
What does 'git rerere' help with during multi-agent work?
1. Automatically splitting large commits
2. Creating new branches quickly
3. Syncing agent codebases together
4. Remembering conflict resolutions across rebases
Why should you run the full test suite after each merge rather than just at the end?
1. Earlier merges may break things that later merges depend on
2. Agents cannot run tests on their own branches
3. Tests run faster on smaller code changes
4. The CI system requires it as a policy
When should you AVOID using multiple parallel agents?
1. When the task involves independent bug fixes in different files
2. When generating tests across multiple modules
3. When the task is under 30 minutes and coordination overhead exceeds the benefit
4. When exploring a large, unfamiliar codebase
What happens when you run 10 agents in parallel in Claude Code?
1. Each agent has its own context and you pay for 10 simultaneous LLM streams
2. Context is automatically shared between all agents
3. The agents automatically coordinate to avoid conflicts
4. All agents share one context to save costs
How should you treat Codex cloud and Cursor cloud background agents?
1. Expect them to finish within your current session
2. Treat them like CI jobs—poll for completion and review results as PRs
3. Ignore them once started—they're self-correcting
4. Stop them immediately if they run longer than 10 minutes
What makes tasks with sequential dependencies unsuitable for parallel agents?
1. They cost too much to run in parallel
2. Agent B cannot start until Agent A finishes
3. The agents will argue about who goes first
4. Sequential tasks require too much memory

← Back to interactive lesson

Tendril · Creators · AI-Assisted Coding

Multi-Agent Coordination — When Subagents Step on Each Other

13 min · Reviewed 2026

Ten Agents, One Repo

When parallelism is a clear win

Task	Why parallel works
Codebase exploration	Each agent reads a different module — no overlap
Independent bug fixes	Different files, different test files, different PRs
Test generation across modules	Agents can each tackle one module's tests
Documentation generation	Each subagent documents one feature area
Migration sweeps	Each agent handles one batch of files for the same migration

When parallelism breaks

Two agents editing the same file — last writer wins, lost work
Refactors that touch shared abstractions — types drift across agents
Tasks with sequential dependencies — agent B can't start until A finishes
Anything where global consistency matters more than local progress

The coordination patterns that work

Pattern	How it works	Best for
Branch-per-agent	Each subagent works on its own git branch; merge at end	Independent feature work, parallel bug fixes
Lane-per-agent	Each agent owns specific paths (paths/A/* vs paths/B/*)	Codebase exploration, parallel module work
Producer-consumer	Agent A produces a plan or spec; Agent B implements	Plan-then-execute workflows
Scout-and-builder	Scouts read and summarize; one builder writes code	Large unfamiliar codebases
Reviewer pair	Builder writes; reviewer (different model) audits	Quality-critical features

A real Claude Code subagent setup

# .claude/agents/scout.md
---
name: scout
description: Read-only codebase exploration
tools: [Read, Grep, Glob]   # NO write/edit tools
---
Your job is to explore and summarize. Never edit files.
Return a Markdown report with file:line references.

# .claude/agents/builder.md
---
name: builder
description: Implementation
tools: [Read, Edit, Write, Bash]
---
Implement based on the plan provided. Run tests after each edit.
Never edit files in test/ or migrations/.

# .claude/agents/reviewer.md
---
name: reviewer
description: Read-only PR review
tools: [Read, Bash]
---
Review the diff. List bugs and risks. Never edit.Three subagents with different tool grants. Scout finds, builder builds, reviewer audits. Roles by permission, not by polite request.

Spawning them right

# In Claude Code main session:

"Spawn a scout subagent. Have it explore src/auth/ and write a
Markdown plan for the refactor we discussed. Wait for its report."

# Once the plan exists:

"Spawn a builder subagent for each of the 4 plan steps in parallel,
with each one on its own branch named refactor/auth-step-1 through 4.
Do not start step 2-4 until step 1's branch passes CI."

# Then:

"Spawn a reviewer subagent for each PR. Aggregate the findings into one report."Sequenced parallelism. Some steps fan out, some serialize. The orchestrator (you, or the main session) decides.

Merge conflict survival

Branch-per-agent is the only safe pattern when changes touch shared code
After all agents finish, merge serially — pick the most surgical first, rebase the rest on top
When two agents propose conflicting changes, do not let a third agent resolve it; you do
Use `git rerere` to remember conflict resolutions across rebases
Run the full test suite after each merge, not just at the end

Communication between agents

When to NOT use multiple agents

Tasks under 30 minutes — coordination overhead exceeds parallelism win
Refactors touching shared types or core abstractions
Anything you wouldn't comfortably hand to multiple junior engineers without coordination
When you don't have CI green on the base branch — agents can't tell what their changes broke

Ten agents in parallel is ten interns who never sleep. Ship the standards, not the code.
— A staff engineer adopting subagents

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-coding-debug-multi-agent-coordination-creators

How many parallel subagents can Claude Code run simultaneously?
1. Up to 10 subagents
2. Up to 20 subagents
3. Up to 5 subagents
4. Unlimited subagents
Which scenario is BEST suited for parallel agent execution?
1. Updating a core abstraction that multiple modules depend on
2. Migrating a database schema that affects all tables
3. Refactoring a shared type used across the entire codebase
4. Running independent bug fixes in different files
Why does parallelism break when two agents edit the same file?
1. Last writer wins and earlier work is lost
2. The file is automatically locked by the system
3. The file becomes corrupted and unreadable
4. The agents get stuck in an infinite loop
What does the 'branch-per-agent' coordination pattern require?
1. Agents share one branch and coordinate through comments
2. Agents must complete work before any branch is created
3. All agents work on the main branch simultaneously
4. Each subagent creates its own git branch and merges at the end
In the 'lane-per-agent' pattern, how is work divided?
1. By time slots—each agent works at a different hour
2. By specific file paths or directory sections
3. By priority level assigned by the orchestrator
4. By model capability—simpler agents get easier lanes
What is the 'producer-consumer' coordination pattern?
1. Agents produce code while humans consume it
2. One agent builds while another watches for errors
3. Agent A creates a plan or spec; Agent B implements it
4. All agents produce output simultaneously for comparison
When is the 'scout-and-builder' pattern most useful?
1. When the codebase is small and well-documented
2. When agents need to test each other's output
3. When all agents need to write code immediately
4. For large, unfamiliar codebases where one agent reads and summarizes before another writes
How do subagents in Claude Code typically communicate with each other?
1. They communicate through code comments in the repository
2. They share direct memory through the orchestrator
3. They write files to disk that other agents can read
4. They send messages through a dedicated chat system
When merging work from multiple branch-per-agent workers, what is the recommended strategy?
1. Let the agents resolve their own conflicts automatically
2. Merge all branches simultaneously in one commit
3. Merge serially, starting with the most surgical changes, then rebase the rest
4. Wait 24 hours before merging to ensure stability
What does 'git rerere' help with during multi-agent work?
1. Automatically splitting large commits
2. Creating new branches quickly
3. Syncing agent codebases together
4. Remembering conflict resolutions across rebases
Why should you run the full test suite after each merge rather than just at the end?
1. Earlier merges may break things that later merges depend on
2. Agents cannot run tests on their own branches
3. Tests run faster on smaller code changes
4. The CI system requires it as a policy
When should you AVOID using multiple parallel agents?
1. When the task involves independent bug fixes in different files
2. When generating tests across multiple modules
3. When the task is under 30 minutes and coordination overhead exceeds the benefit
4. When exploring a large, unfamiliar codebase
What happens when you run 10 agents in parallel in Claude Code?
1. Each agent has its own context and you pay for 10 simultaneous LLM streams
2. Context is automatically shared between all agents
3. The agents automatically coordinate to avoid conflicts
4. All agents share one context to save costs
How should you treat Codex cloud and Cursor cloud background agents?
1. Expect them to finish within your current session
2. Treat them like CI jobs—poll for completion and review results as PRs
3. Ignore them once started—they're self-correcting
4. Stop them immediately if they run longer than 10 minutes
What makes tasks with sequential dependencies unsuitable for parallel agents?
1. They cost too much to run in parallel
2. Agent B cannot start until Agent A finishes
3. The agents will argue about who goes first
4. Sequential tasks require too much memory

← Back to interactive lesson