You ran Claude Code on “fix billing bug” and Codex on “refactor billing structure” at the same time, on the same branch. Both touched src/billing.ts. Now git status shows conflicted files, both agents disagree about whose changes are “right,” and your test suite fails because each agent’s tests assume a different state of the file.
Fastest fix: if you’re mid-merge, run git merge --abort to get back to a clean state, then stop both agents. Resolve the conflict yourself (or with git mergetool) — never prompt an agent to “resolve this merge conflict,” because the agent that didn’t write the other side has no way to recover its intent. Then prevent the recurrence: give each agent a disjoint file scope and put each one in its own git worktree.
The structural cause is shared state. Two agents reading the same files make different decisions and produce conflicts that neither should resolve. As of June 2026 both major coding agents have built worktree isolation directly into their tooling for exactly this reason. In the OpenAI Codex app you pick Worktree mode (vs Local / Cloud) when you start a thread, and it checks out an isolated worktree on the branch you selected; you merge back deliberately with its built-in git tools (commit / push / open PR) or the Hand off button — it never auto-merges. Claude Code gives each session a --worktree flag and lets custom subagents carry isolation: worktree in their frontmatter. The fix below works whether you use that automation or wire worktrees by hand.
Which bucket are you in?
| Symptom | Likely cause | Jump to |
|---|---|---|
git status shows both modified files after a merge/rebase | Overlapping scopes on the same branch | Causes 1-2, Steps 1-4 |
| Edits appear then vanish in one terminal while another writes | Two agents, one working tree | Cause 3, Step 4 |
| A long-running agent overwrote work you did later | Background agent + foreground edits | Cause 4, Step 4 |
| Merged file is “clean” but one task’s logic is gone | An agent guessed at the resolution | Cause 5, Steps 2 + 5 |
Conflict is only in CLAUDE.md / package.json / lockfiles | Shared config, physical collision | Cause 6, Step 6 |
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. Run git diff --name-only --diff-filter=U — if the conflicted list overlaps both task descriptions, 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 -rl "billing" src/ 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 then disappearing as the other terminal writes. File modification times (ls -la --time-style=full-iso src/) are interleaved between the two sessions.
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. A long-running or seemingly stalled agent can still flush a large batch of writes minutes after you’ve moved on, landing on top of files you’ve since touched.
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 --oneline shows a “resolve conflict” commit authored during an agent run. The merged file doesn’t represent either branch’s full intent, and the other task’s tests now fail.
6. Shared CLAUDE.md / configuration created false-positive conflicts
Two agents both updated CLAUDE.md, package.json, or a lockfile (package-lock.json, pnpm-lock.yaml) for slightly different reasons — different intent, but git can’t auto-merge if the edited lines are physically close or the lockfile regenerated.
How to spot it: Conflicts in config / docs / lockfiles, 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 4 prevents recurrence.
Step 1: Stop both agents and freeze the merge
First stop both Claude Code and Codex (or whichever pair). Every continued run by either agent compounds the conflict.
If a merge or rebase is currently half-applied and you want a clean slate before deciding anything, abort it:
git merge --abort # if you're mid-merge
git rebase --abort # if you're mid-rebasegit merge --abort returns the working tree to the exact state before the merge started, so you can re-plan instead of editing inside a broken merge. Do not re-run either agent until the merge is resolved.
Step 2: Resolve the conflict as a human
# See exactly what conflicts exist
git status
git diff --name-only --diff-filter=U # only conflicted filesOpen each conflicted file. Git marks the two sides with these markers:
<<<<<<< HEAD
your current branch's version
=======
the incoming branch's version
>>>>>>> feature/refactor-billingEdit the file to keep what you want, then delete all three marker lines (<<<<<<<, =======, >>>>>>>). For a guided three-way view, run git mergetool instead of editing raw markers. For 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, run
git checkout --theirs <file>or--ours <file>to reset that one file, or revert it entirely and re-plan.
When done:
git add <resolved-files>
git commit -m "resolve conflict between feature-billing and feature-refactor"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. When in doubt, grep -rl "<shared-concept>" src/ first to confirm the scopes really don’t intersect — names lie.
Step 4: Use git worktrees to isolate parallel work
A worktree is a second checkout linked to the same repository. Each worktree has its own branch, its own index, and its own files on disk, but they share one commit history. Two agents can write into separate worktrees without ever colliding.
# Main project for one agent (already checked out on, say, feature/billing)
cd ~/projects/myapp
# Separate worktree on a new branch for the other agent
git worktree add -b feature/auth ../myapp-agent2
# List all worktrees to confirm
git worktree list-b feature/auth creates the branch and checks it out into ../myapp-agent2 in one step. Point the second agent at that directory. Merge happens as a deliberate step:
git checkout main
git merge feature/billing
git merge feature/auth
# Resolve any remaining conflicts manually (see Step 2)A worktree is a fresh checkout, so gitignored files like .env aren’t copied into it. With Claude Code, add a .worktreeinclude file (it uses .gitignore syntax) at your repo root listing the local files to copy into each new worktree:
.env
.env.local
config/secrets.jsonWhen a worktree is finished, clean it up so stale checkouts don’t pile up:
git worktree remove ../myapp-agent2
git worktree prune # drop bookkeeping for any already-deleted worktreesUsing the built-in tooling (June 2026): you don’t always have to wire this by hand.
- Claude Code: start any session in its own tree with
claude --worktree feature-auth(or-w). By default it creates.claude/worktrees/feature-auth/on a branch namedworktree-feature-auth; add.claude/worktrees/to your.gitignore. To make code-writing subagents isolate themselves, addisolation: worktreeto the subagent’s frontmatter — each gets a temporary worktree that’s removed automatically when it finishes with no changes. Worktrees branch fromorigin/HEAD(a clean tree) by default; setworktree.baseRefto"head"in settings if you instead need them to carry your in-progress commits. - Codex app: choose
Worktreemode when you start a thread; it isolates that task on its own checkout and you merge back deliberately with its built-in git tools orHand off. - Codex CLI: it has no built-in
--worktreeflag yet (as of June 2026), so create worktrees with plaingit worktree addand export a distinctCODEX_HOMEper worktree (e.g.export CODEX_HOME=../myapp-agent2/.codex) so the parallel agents don’t share session/config state.
Step 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. This is also why the Codex app and most serious worktree tooling force a manual merge rather than auto-merging.
Do NOT prompt either agent with: "resolve this merge conflict."
Instead: resolve manually (Step 2), then re-prompt each agent with the now-clean state.Step 6: For shared config files, manually coordinate updates
CLAUDE.md, package.json, .eslintrc, lockfiles — 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) and the lockfile
- .eslintrc, tsconfig.json
- migrations/
Only one agent at a time may touch these.How to confirm it’s fixed
git statusreportsnothing to commit, working tree cleanand lists noboth modifiedpaths.git diff --checkreturns nothing — there are no leftover conflict markers anywhere in the tree.- Your full test suite passes, including the tests both tasks added (a guessed resolution usually leaves one task’s tests red).
git worktree listshows only the worktrees you intend to keep.
Prevention
- Plan disjoint file scopes before running parallel agents — overlap = guaranteed conflict
- Use git worktrees (or the built-in worktree isolation in Codex / Claude Code subagents) for any parallel agent or parallel-plus-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, lockfiles), 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 -rlfor shared files first to verify — names lie
FAQ
Should I just let Claude or Codex resolve the conflict since they wrote the code? No. The agent that resolves it can only see code, not the reasoning behind the other agent’s edits, so it silently drops one task’s intent. Resolve manually, then hand each agent the clean state to continue.
Do git worktrees fully prevent conflicts? They prevent file-system collisions while agents work — two agents can never overwrite each other’s files. You can still get a normal merge conflict when you merge the branches back if their scopes overlapped, which is why disjoint scopes (Step 3) matter even with worktrees.
My merge is half-applied and looks like a mess — how do I start over?
Run git merge --abort (or git rebase --abort). That restores the working tree to its pre-merge state with no edits lost on either branch, so you can re-plan before trying again.
The conflict is only in package-lock.json / pnpm-lock.yaml. Do I hand-edit it?
No. Resolve package.json first, delete the conflicted lockfile, then regenerate it with npm install / pnpm install so it matches the merged manifest exactly.
How do I check no conflict markers slipped through?
Run git diff --check. It flags any leftover <<<<<<<, =======, or >>>>>>> lines and whitespace errors before you commit.
Do I still need manual git worktree commands now that Claude Code and Codex have built-in worktrees?
For one-off parallel work, no — claude --worktree <name> and the Codex app’s Worktree mode handle creation and cleanup for you. Reach for manual git worktree add when you need a specific existing branch, a worktree outside the repo, or when driving the Codex CLI, which has no built-in worktree flag yet (as of June 2026).
Related
- Claude Code wrong file edit
- Multi-agent coding workflow
- Claude Code beginner guide
- Claude Code workflow
- Claude Code project setup
External references: git-worktree documentation, git-merge —abort, Claude Code worktrees, Codex app worktrees.