You ran Claude Code on the “fix billing bug” task and Codex on the “refactor billing structure” task — at the same time, on the same branch. Both touched src/billing.ts. Now git is showing a merge conflict, both agents are confused about whose changes are “right,” and your test suite is failing because each agent’s tests assume a different state of the file.
Parallel agents need scope separation. Without it, they read the same file, make different decisions, and produce conflicts that neither agent should resolve — agent-driven merge resolution is how you get the worst of both branches. The fix: assign disjoint file paths up front, use git worktrees to isolate working trees, and resolve any conflicts as a deliberate human step.
Common causes
Ordered by hit rate, highest first.
1. No scope separation before parallel runs
You started both agents on the same branch with overlapping task scopes. Each read the original state of shared files, edited based on its own interpretation, and you discovered the overlap on the merge.
How to spot it: Two recent commits or in-progress branches that both touch the same files. The overlap was structural — not bad luck.
2. Tasks looked independent but had hidden coupling
“Fix billing bug” and “refactor billing structure” sound disjoint. They aren’t — both need billing.ts. The independence was nominal.
How to spot it: grep -l "billing" src/**/*.ts shows many shared files. Tasks named for the same concept usually overlap.
3. Both agents share a single working tree
Same repo, same branch, two terminal sessions. The second agent reads the first agent’s mid-task state, gets confused, writes over it.
How to spot it: One terminal’s edits appearing/disappearing as the other terminal writes. File timestamps are interleaved.
4. Background long-running agent + foreground edits
You set a Claude Code agent on a long task, then started editing manually (or with another agent). The background agent’s eventual writes collide with your fresh edits.
How to spot it: A previously-stalled or long-running agent finishes after you’ve moved on. Its output overwrites your newer work.
5. One agent “resolved” the conflict by guessing
After a real conflict, you asked one of the agents to fix it. It picked a direction, but the other agent’s intent is now lost — the resolution looks clean but the other task’s logic is gone.
How to spot it: git log shows a “resolve conflict” commit by an agent. The merged file doesn’t represent either branch’s full intent.
6. Shared CLAUDE.md / configuration created false-positive conflicts
Two agents both updated CLAUDE.md or package.json for slightly different reasons — different lines, but git can’t auto-merge if they’re close.
How to spot it: Conflicts in config / docs files, not code. Each agent’s addition is valid; they just collided physically.
Shortest path to fix
Ordered by ROI. Step 1 stops the bleed; Step 2 prevents recurrence.
Step 1: Stop both agents immediately
Stop both Claude Code and Codex (or whichever pair).
Do NOT re-run either agent until merge is resolved.Every continued run by either agent compounds the conflict.
Step 2: Resolve the conflict as a human
# See exactly what conflicts exist
git status
git diff --name-only --diff-filter=U # only conflicted files
# For each conflicted file, open and manually choose
# Do NOT let an agent merge — agent guessing here is dangerousFor each conflict, decide:
- Is one direction obviously right? Keep that direction, discard the other.
- Are both needed? Manually combine them carefully.
- If you can’t tell, revert the file entirely and re-plan.
When done:
git add <resolved-files>
git commit -m "resolve conflict between feature-X and feature-Y"Step 3: Plan disjoint scopes for the next parallel run
Agent A scope (only): src/billing/
Agent B scope (only): src/auth/
If either agent needs to edit outside its scope:
- STOP
- Wait for the other agent to finish
- Then proceed sequentiallyDisjoint file paths = no possible conflict. Plan this before starting.
Step 4: Use git worktrees to isolate parallel work
# Main project for one agent
cd ~/projects/myapp
# Separate worktree for the other agent
git worktree add ../myapp-agent2 feature/auth
# Now each agent has its own working tree on its own branchEach worktree has its own files on disk. Two agents can write without colliding. Merge happens as a deliberate step:
git checkout main
git merge feature/billing
git merge feature/auth
# Resolve any remaining conflicts manuallyStep 5: Never let an agent resolve a conflict
Even capable agents lose the intent of the other side when they pick a direction. Agents see code, not why it was written. Resolution requires understanding both intents — humans do this, agents don’t.
Do NOT prompt either agent with: "resolve this merge conflict."
Instead: resolve manually, then re-prompt each agent with the now-clean state.Step 6: For shared config files, manually coordinate updates
CLAUDE.md, package.json, .eslintrc — files multiple agents may want to touch. Either:
- Forbid agents from editing them (“only humans edit CLAUDE.md”)
- Or coordinate timing — one agent at a time on these files
# CLAUDE.md
## Files agents must not modify in parallel
- This file (CLAUDE.md)
- package.json (engines, scripts)
- .eslintrc, tsconfig.json
- migrations/
Only one agent at a time may touch these.Prevention
- Plan disjoint file scopes before running parallel agents — overlap = guaranteed conflict
- Use git worktrees for any parallel agent + manual editing — separate working trees can’t collide
- Forbid agents from resolving merge conflicts; merge is a deliberate human step
- For shared config files (CLAUDE.md, package.json), allow only one writer at a time
- Sequential is often safer than parallel — only parallelize when scopes truly don’t overlap
- When tasks look independent, grep for shared files first to verify — names lie