Resolving merge conflicts with Claude Code

A Claude Code merge conflict happens when two agents change the same lines on different branches: git stops when the second branch meets the first. Merge one branch, rebase the next onto it, and run git status to list the conflicted files. Ask Claude Code to resolve them with both branches' goals in the prompt, have it run your tests before git rebase --continue, and abort if the result looks wrong.

Why worktrees don't stop merge conflicts#

A git worktree gives each Claude Code session "a separate copy of the files to edit", and Anthropic's docs are exact about the scope: worktrees "isolate file edits" (Claude Code docs: worktrees). claude --worktree feature-auth starts the session in .claude/worktrees/feature-auth/ on a new branch, worktree-feature-auth, cut from your default branch. While they work, two agents can't overwrite each other's files.

They can both edit routes.ts, though. Each branch passes on its own, and the clash shows up only when the second one is merged into a main that already has the first. Isolation moves the conflict from "while they work" to "when you merge", and at merge time git stops and prints CONFLICT (content): Merge conflict in src/routes.ts. In one shared folder the same overlap makes no noise at all; our Claude Code git workflow tells how we lost an agent's uncommitted edits that way.

The merge order that keeps conflicts small#

With three agents done, take them one at a time:

1. Merge the branch with the smallest or most central change first.
2. In the next branch's worktree, run git rebase main.
3. Resolve whatever that rebase stops on, run the tests, merge.
4. Repeat for the branch after it.

Each rebase then reconciles one branch against code that already passed its tests. Merging three branches into each other at once asks git, and Claude, to weigh three sets of intent inside one conflict. Merge each branch soon after it's done, too: a branch that sits for two days collects conflicts from everything merged in between. Splitting the work so fewer files overlap in the first place is covered in running Claude Code agents in parallel.

Turn on one git setting before the first conflict: git config merge.conflictStyle zdiff3. Git's default markers show the two sides. The diff3 and zdiff3 styles add the original text between them, under a ||||||| line, so you and Claude can see what each side changed from as well as where it ended up; zdiff3 also moves lines both sides share out of the start and end of each conflict (git merge docs).

How to hand a merge conflict to Claude Code#

When the rebase stops:

1. Run git status. The files under "Unmerged paths" are the conflicts.
2. Ask Claude Code in that worktree. The session that wrote the branch is best, since it already knows what it changed.
3. Give it both intents. "Fix the conflicts" on its own leaves it guessing which side matters:

We're rebasing worktree-feature-auth onto main and hit conflicts in
src/routes.ts and src/session.ts. Our branch adds token refresh to the
login route. The commit on main renamed getUser to loadUser and moved
session handling into session.ts. Keep both changes. Show me each
resolution before staging it, then run npm test.

4. Read each resolution in git diff before it's staged.
5. Let it run the tests on the resolved files. Only after they pass, git add the files and git rebase --continue.
6. A rebase replays your commits one at a time, so commit 3 of 5 can stop with a conflict of its own. Same loop.

Watch the words "ours" and "theirs". During a rebase, git's "ours" is main plus the commits already replayed, and "theirs" is your branch; git's own docs say "the sides are swapped" compared with a merge (git rebase docs). Tell Claude "keep ours" meaning your branch, and you get main's version. Name the branch instead: "keep worktree-feature-auth's version of refreshToken".

What to check yourself before you continue#

Claude Code sees the conflict markers and the code around them. Unless you said which side mattered more, it has to guess, and a resolution can compile and still drop half the work. We check three things by hand at this point (the rest of our order for reading an agent's diff is in how to review AI-generated code).

Deleted code#

The usual bad resolution keeps one side whole and loses a function the other side added. Right after the rebase, git range-diff main @{1} @ compares your branch's commits before and after it. Git's range-diff docs give this check (with @{u} where we wrote main) for "when a rebase required merge conflicts to be resolved" (git range-diff docs). Read any commit whose diff shrank.

Lockfiles#

Nobody, Claude included, should merge package-lock.json line by line. npm's docs say that since npm 5.7.0 you fix any package.json conflict by hand, then run npm install (or npm install --package-lock-only to leave node_modules alone) and npm merges the lockfile itself (npm docs: package-locks). With pnpm, Yarn or Cargo, resolve the manifest and regenerate the lockfile the same way.

Migrations#

Two branches that each add a migration usually merge without a git conflict, since each adds its own file. They break later: both take number 0042, or both alter the same table and only one order runs. After every rebase, clean ones included, list the migrations folder and run the migrations against an empty database.

When to abort instead#

git rebase --abort resets the branch to where it was when the rebase started (git rebase docs). We abort in three cases:

• Both branches rewrote the same function in different ways, so the conflict covers most of a file. We merge one branch, then ask an agent to redo the other's change on top of the new main; that's easier than merging text.
• The resolution needs a second round of "no, keep both".
• The tests fail in ways neither branch explains.

If you already continued and the result is wrong, ORIG_HEAD records where the branch was before the rebase (gitrevisions). git reset --hard ORIG_HEAD goes back to it, as long as nothing has moved it since, and throws away uncommitted changes in that worktree. Claude Code's /rewind won't help here. Its checkpoints restore file contents, not commits or branches, and "a file that only Bash commands changed isn't tracked" (checkpointing docs). Git runs through Bash. Undoing Claude Code changes lists the other ways back.

Merge conflicts in Claude Code cloud sessions#

A cloud session can watch a pull request with auto-fix, which reacts to failing CI checks and review comments. Conflicts are the exception, in Anthropic's words: "GitHub does not emit a webhook when the base branch advances and creates a merge conflict, so auto-fix can't react to conflicts on its own. To resolve a conflict, open the session and ask Claude to rebase." (Claude Code docs: cloud sessions). When GitHub shows "This branch has conflicts that must be resolved" on a pull request a cloud session opened, go to the session and ask. The prompt with both intents works there too.

How Shuriken resolves merge conflicts for you#

In Shuriken every chat in a project except the Main chat works on its own branch in its own worktree, so we meet this case more than any other. Finish does the ending: it waits for the turn to end, commits what's left, catches up with your default branch, runs the checks you list under checks in shuriken.json, squash-merges, then removes the branch and its worktree. For a project with a GitHub remote it can push instead and open a pull request with auto-merge on.

A conflict goes back to the agent that wrote the branch. The chat shows "Finish: src/routes.ts conflicts with main", and the agent gets this prompt: "Run git merge main in this folder, resolve every conflict so both changes are kept, then git add the files and git commit --no-edit. Do not push and do not switch branches." Finish then tries the merge again, up to three times, each attempt a row such as "1/3 · Asked the agent to fix it". Finishes in one repository run one at a time ("Waiting to merge" on the second), so two chats that touched the same file merge in turn and the second resolves against the first: the order above, without you keeping track of it.

If the agent can't settle it, Finish stops with "Couldn't merge", names the files and leaves the branch unmerged. The card offers Ask the agent again, Keep this chat's version and Keep main's version (with your default branch's name in place of main). Finish: checks, rebase and merge in one click has every step.

Shuriken 5.1 adds forks: fork a chat from one of the agent's replies to try a second approach, and a fork made as a new chat gets its own branch. When it wins, Merge into, followed by the parent chat's name, brings the fork's work back into the parent's branch and leaves a note in the parent chat saying what the fork did. Download Shuriken to try Finish on your own repository.