Merge conflicts are an unavoidable part of software development when working in a team, or even solo, especially when running multiple agents in parallel. Even if you do your best to organize work for agents so that parallel tasks don't touch the same area of the codebase, conflicts will invariably occur at some point.
Fortunately, the agent you built the feature with can probably resolve the conflicts for you. If you still have the same session open, the agent should have good context on how to resolve the diffs in a way that preserves the new feature. What it might be missing though is context on the changes in the base branch that caused the conflicts.
Prompting Claude Code to simply resolve the conflicts might be enough for it to
do sufficient groundwork, but to make the process more reliable I've recently
set up the following /rebase custom command to streamline
rebasing current branch on the main branch. It specifically instructs Claude
to understand the intent behind the changes in the target branch before
resolving conflicts, which appears to help.
Rebase the current branch.
Arguments: $ARGUMENTS
Behavior:
- No arguments: rebase on local main
- "origin": fetch origin, rebase on origin/main
- "origin/branch": fetch origin, rebase on origin/branch
- "branch": rebase on local branch
Steps:
1. Check for uncommitted changes:
- Run `git status --porcelain`
- If there are changes, run `git stash push -m "rebase-temp"`
- Remember to pop the stash after rebase completes
2. Parse arguments:
- No args → target is "main", no fetch
- Contains "/" (e.g., "origin/develop") → split into remote and branch, fetch
remote, target is remote/branch
- Just "origin" → fetch origin, target is "origin/main"
- Anything else → target is that branch name, no fetch
3. If fetching, run: `git fetch <remote>`
4. Run: `git rebase <target>`
5. If conflicts occur, handle them carefully (see below)
6. Continue until rebase is complete
7. If changes were stashed in step 1, run `git stash pop`
Handling conflicts:
- BEFORE resolving any conflict, understand what changes were made to each
conflicting file in the target branch
- For each conflicting file, run `git log -p -n 3 <target> -- <file>` to see
recent changes to that file in the target branch
- The goal is to preserve BOTH the changes from the target branch AND our
branch's changes
- After resolving each conflict, stage the file and continue with
`git rebase --continue`
- If a conflict is too complex or unclear, ask for guidance before proceeding
To rebase on main, run it with /rebase, or /rebase origin to also fetch
and rebase on origin/main.
Here's what it looks like in practice when rebasing onto a branch that has refactored the codebase:
> /rebase tori-login
⏺ Bash(git rebase tori-login)
⎿ Error: Exit code 1
error: could not apply 88adb7e... add llm-based category auto-selection
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".
…
⏺ I see there's a significant conflict. The tori-login branch has refactored
bot.go to use handlers (AuthHandler, ListingHandler), while my commit still
uses the old structure. Let me understand the changes in the target branch
first:
⏺ Bash(git log -p -n 3 tori-login -- bot.go | head -200)
⎿ commit 67c20e028872a455fb057e35b2a635503a690107
Author: Raine Virta <[email protected]>
Date: Sun Dec 28 19:21:25 2025 +0200
…
⏺ My commit needs to:
1. Use llm.Analyzer instead of vision.Analyzer
2. Add /osasto command to handle category re-selection
3. Add category auto-selection using LLM
The conflicts are:
1. Import section - need to use llm instead of vision
2. Bot struct - need to use llm.Analyzer
…
The key behavior here is that Claude examines the target branch's changes with
git log -p before attempting to resolve conflicts, giving it context on the
refactoring that occurred.