Running multiple Claude Code agents at the same time sounds great until two of them edit the same file and you spend an hour untangling a merge conflict that shouldn't exist.
Here's what actually works.
The core problem
Agents don't know about each other. Agent A is refactoring your auth module. Agent B is adding a feature that touches the same auth module. They both read the same state, make different changes, and now you have a conflict neither one can resolve because neither one knows the other exists.
The naive fix is to not run them in parallel. But that's slow.
Task partitioning first
Before spawning anything, split work by file ownership. Each agent gets a zone it owns exclusively:
- Agent A: everything in
/lib/auth/ - Agent B: everything in
/components/dashboard/ - Agent C: everything in
/api/routes/ - Agent D: tests only, no source files
The rule: if two tasks touch overlapping files, they run sequentially. Everything else runs in parallel.
This sounds obvious but most people don't do it systematically. They think "these tasks seem different" without actually checking the file overlap.
The shared state problem
Even with file partitioning, agents share a few things that conflict:
-
package.json- if two agents both try to add a dependency -
.env.local- if any agent reads environment state - Git index - if you're letting agents commit
For package.json, I have one rule: only one agent is allowed to touch dependencies. The others request additions through a queue file - they append to tasks/dep-requests.md and the main agent handles it.
For git, I don't let agents commit automatically. They stage changes and I review before committing. Too many bad experiences with "fixed tests" commits that quietly broke something else.
CLAUDE.md as coordination layer
Each parallel session gets a CLAUDE.md that specifies its zone:
## Your scope
You own: /lib/payments/
You may NOT touch: /lib/auth/, /components/, package.json
If you need a new dependency, append it to tasks/dep-requests.md
Agents respect this. Not perfectly, but well enough that conflicts drop from constant to rare.
The context isolation trick
One thing that makes parallel agents worse than they need to be: they all read the full codebase and build overlapping context. Agent A learned about the auth module even though it has no business touching it.
I use .claudeignore to limit what each agent sees. If Agent B is working on dashboard components, it doesn't need to see the payments library or the migration scripts. Smaller context means faster responses and fewer helpful edits outside the assigned scope.
I wrote about .claudeignore patterns in detail here if you want the full breakdown.
What I actually run
For a medium-sized feature, the setup looks like this:
- Planner agent (read-only, full codebase access) - figures out what needs to change and creates the partition plan
- 2-3 executor agents in parallel - each with scoped CLAUDE.md and scoped .claudeignore
- Verifier agent (read-only, full codebase access) - checks the combined output makes sense together
The planner and verifier run sequentially. The executors run in parallel. Total time is roughly the length of the longest executor task plus overhead.
The failure mode nobody talks about
The most common thing that breaks this: tasks that seem independent but have a shared read dependency.
Agent A is writing a new API endpoint. Agent B is writing tests for a different endpoint. Looks fine. But Agent B reads the shared test helpers file to understand patterns, then Agent A adds a new test helper, and now Agent B's tests use the old pattern and look inconsistent compared to what A wrote.
Fix: if agents need to read shared infrastructure (helpers, utilities, config), run them sequentially or snapshot the shared files before starting rather than letting agents read live state.
The setup cost is maybe 20 minutes for a new project. After that it mostly runs without drama.
If you want the CLAUDE.md templates and .claudeignore patterns for parallel agents, they're in the Claude Code Playbook - $29, covers this plus about 40 other patterns I use daily.
Top comments (0)