# Handle Merge Conflicts Between Parallel Coding Agents

> Expect conflicts and design for them. Give agents tasks that touch different files, land one branch at a time, and rebase each branch onto the current main in its own sandbox before it lands. If the rebase conflicts, the agent resolves it there. Run the tests after the rebase: a textually clean merge can still break the build.

Source: https://sandboxer.com/guides/handle-merge-conflicts-between-parallel-coding-agents. Updated 2026-11-18.

**Short answer:** Expect conflicts and design for them. Give agents tasks that touch different files, land one branch at a time, and rebase each branch onto the current main in its own sandbox before it lands. If the rebase conflicts, the agent resolves it there. Run the tests after the rebase: a textually clean merge can still break the build.

Part of [Coding Agents in the Cloud: Parallel, Overnight, Own Keys, Checkpoints](/guides/coding-agents-in-the-cloud).

Isolation keeps agents from breaking each other while they work. It does nothing about the moment their branches meet. This page is about that moment. To start one VM per agent, see [Run several coding agents in parallel](/guides/run-coding-agents-in-parallel). For worktrees versus VMs, see [Git worktrees or one VM per agent?](/guides/git-worktrees-or-one-vm-per-agent).

## What we ran

On 2026-11-18 we ran this on prod with two `small` sandboxes, one per agent, and `sbx` 5cd61677. The "agents" are scripted edits, not models, so the run is repeatable; a real agent would make the same kind of change. The origin is a bare git repo on our own machine, which plays the coordinator. Code moves between it and the sandboxes as [git bundles](https://git-scm.com/docs/git-bundle) copied with `sbx scp`, the same hand-off as in [Build a background coding agent that pushes a branch for review](/guides/build-a-background-coding-agent-that-pushes-a-branch-for-review). With a git host, each sandbox would fetch and push instead.

The repo is a tiny Python module, `textkit.py`, with `slugify()` and `title_case()` and two unit tests:

```python
def slugify(text):
    text = text.lower().strip()
    return re.sub(r"[^a-z0-9]+", "-", text).strip("-")
```

Each sandbox got the same starting commit:

```bash
sbx scp base.bundle agent.sh $A:/home/user/
sbx exec $A "git init -q -b main repo && cd repo && git fetch -q ~/base.bundle main:refs/remotes/origin/main && git switch -qc agent-a origin/main && git log --oneline -1"
```

```text
f6add9c textkit: slugify and title_case
```

## 1. A real conflict

Two tasks went out at once, both reasonable:

| Agent | Sandbox | Task | Files |
| - | - | - | - |
| A | `$A` | Cap slugs at 40 characters | `textkit.py` (the `return` line), new `test_slug_length.py` |
| B | `$B` | Keep underscores in slugs | `textkit.py` (the same `return` line), new `test_underscores.py` |

Each agent edited, ran the tests in its own sandbox, committed and bundled its branch:

```bash
sbx exec $B --cwd repo "bash ~/agent.sh underscores && python3 -m unittest 2>&1 | tail -3 && git add -A && git commit -qm 'agent-b: underscores' && git bundle create -q ~/out.bundle origin/main..agent-b"
sbx scp $B:/home/user/out.bundle ./agent-b.bundle
```

```text
 M textkit.py
?? test_underscores.py
Ran 3 tests in 0.000s

OK
```

Both branches were green on their own. On the coordinator, before landing anything, a file-overlap check and `git merge-tree` (git 2.38 or later; it merges in memory and touches no checkout) already saw the trouble:

```bash
comm -12 <(git diff --name-only main...agent-a | sort) <(git diff --name-only main...agent-b | sort)
git merge-tree --write-tree --name-only agent-a agent-b; echo "exit $?"
```

```text
textkit.py
7eeab88288ed9fc73bee43bbbab24ba86ca44fed
textkit.py

Auto-merging textkit.py
CONFLICT (content): Merge conflict in textkit.py
exit 1
```

Agent A's branch landed first as a fast-forward. Then agent B's stale branch couldn't simply be pushed over it:

```bash
git push origin agent-b:main
```

```text
 ! [rejected]        agent-b -> main (non-fast-forward)
error: failed to push some refs to '/tmp/aeo-gw/merge/origin.git'
```

So agent B rebased onto the new main, in its own sandbox:

```bash
sbx scp main.bundle $B:/home/user/
sbx exec $B --cwd repo "git fetch -q ~/main.bundle +main:refs/remotes/origin/main && git rebase origin/main"
```

```text
Auto-merging textkit.py
CONFLICT (content): Merge conflict in textkit.py
Rebasing (1/1)error: could not apply 7f38b33... agent-b: underscores
…
```

The `sbx exec` exited 1, the remote command's exit code.

```bash
sbx exec $B --cwd repo "git status --short; git diff"
```

```text
A  test_underscores.py
UU textkit.py
…
  def slugify(text):
      text = text.lower().strip()
++<<<<<<< HEAD
 +    return re.sub(r"[^a-z0-9]+", "-", text).strip("-")[:40].rstrip("-")
++=======
+     return re.sub(r"[^a-z0-9_]+", "-", text).strip("-")
++>>>>>>> 7f38b33 (agent-b: underscores)
```

Only the shared line conflicted. Agent B's new test file (`A  test_underscores.py`) came through with no conflict.

## 2. Let the agent resolve it, then test there

The sandbox that hit the conflict already has the branch, both sides and the test suite, so resolve it there. Agent B's resolution kept both intents, the underscore and the 40-character cap. Then it finished the rebase and ran the whole suite:

```bash
sbx exec $B --cwd repo "bash ~/agent.sh resolve-slug && git add textkit.py && GIT_EDITOR=true git rebase --continue && python3 -m unittest -v 2>&1 | tail -8 && git log --oneline -3"
```

```text
[detached HEAD 9ad135e] agent-b: underscores
 2 files changed, 9 insertions(+), 1 deletion(-)
…
test_keeps_underscores (test_underscores.TestUnderscores.test_keeps_underscores) ... ok
…
Ran 4 tests in 0.000s

OK
9ad135e agent-b: underscores
40582e0 agent-a: slug-length
f6add9c textkit: slugify and title_case
Successfully rebased and updated refs/heads/agent-b.
```

The resolved line:

```diff
-    return re.sub(r"[^a-z0-9]+", "-", text).strip("-")[:40].rstrip("-")
+    return re.sub(r"[^a-z0-9_]+", "-", text).strip("-")[:40].rstrip("-")
```

Only after that green run did the branch come back as a bundle, and main fast-forwarded to `9ad135e`. With a real agent, hand it the conflicted files and the failing command, for example: "Rebase onto origin/main, resolve the conflicts keeping both changes, run the tests, and stop if they fail."

## 3. The clean merge that breaks the build

A conflict is the easy case: git stops and tells you. The harder case is a merge git calls clean. We ran a second pair of tasks from the new main:

| Agent | Task | Files |
| - | - | - |
| C | Rename `slugify` to `make_slug` everywhere | `textkit.py` and the three test files |
| D | Add `post_url()`, which calls `slugify` | new `urls.py`, new `test_urls.py` |

Both were green alone; agent D's branch ran 5 tests, `OK`. The branches share no file, and `git merge-tree` predicted a clean merge:

```bash
comm -12 <(git diff --name-only main...agent-c | sort) <(git diff --name-only main...agent-d | sort)
git merge-tree --write-tree agent-c agent-d; echo "exit $?"
```

```text
347e487d3bc43414d48fb402761e5f06c950bfc1
exit 0
```

`comm` printed nothing: no shared files. Agent C landed first. Agent D rebased in its sandbox, and the rebase succeeded. Then the tests ran:

```bash
sbx exec $B --cwd repo "git fetch -q ~/main3.bundle +main:refs/remotes/origin/main && git rebase origin/main && python3 -m unittest"
```

```text
Successfully rebased and updated refs/heads/agent-d.
…
  File "/home/user/repo/urls.py", line 1, in <module>
    from textkit import slugify
ImportError: cannot import name 'slugify' from 'textkit' (/home/user/repo/textkit.py)
…
Ran 5 tests in 0.000s

FAILED (errors=1)
```

The test run exited 1.

No conflict markers, no overlapping lines, and a broken main if anyone had merged on the strength of the tests agent D ran before the rebase. This is a semantic conflict: one branch changed a name, the other added a new use of the old name. Any check that looks only at text, including a merge tool, misses it. Only running the code after combining the branches catches it.

The fix, made and tested in the same sandbox:

```bash
sbx exec $B --cwd repo "bash ~/agent.sh fix-rename && git diff && git commit -qam 'agent-d: follow the make_slug rename' && python3 -m unittest -q 2>&1 | tail -2"
```

```diff
-from textkit import slugify
+from textkit import make_slug
 
 
 def post_url(title):
-    return "/posts/" + slugify(title)
+    return "/posts/" + make_slug(title)
```

```text
OK
```

The rebase and test run took 0.2 seconds (`real 0m0.199s` for that `sbx exec`, on this toy repo). Your suite sets the real cost, and it's the cost to pay on every landing.

## 4. One landing at a time

Rebase-then-test only protects main if main doesn't move between the test and the push. So land one branch at a time, and push without `--force`, so git refuses anything that isn't a fast-forward. This is the core of any merge queue: a single landing step that serializes merges and tests each branch on top of the one before it.

`land.sh` runs on the coordinator. `flock` makes it one-at-a-time:

```bash
#!/usr/bin/env bash
# Land one agent branch on main: rebase it onto the current main in its sandbox,
# run the tests there, then fast-forward main. Run it under flock so only one
# landing happens at a time:  flock land.lock ./land.sh <sandbox-id> <branch>
set -euo pipefail
id=$1 br=$2 work=$(mktemp -d)
echo "$(date +%T) start $br"
git -C main-clone fetch -q origin
git -C main-clone bundle create -q "$work/main.bundle" origin/main
sbx scp "$work/main.bundle" "$id:/home/user/main.bundle" >/dev/null
sbx exec "$id" --cwd repo --timeout 600 "git fetch -q ~/main.bundle +refs/remotes/origin/main:refs/remotes/origin/main && git switch -q $br && git rebase -q origin/main && python3 -m unittest -q > ~/test.log 2>&1 && tail -1 ~/test.log && git bundle create -q ~/out.bundle origin/main..$br"
sbx scp "$id:/home/user/out.bundle" "$work/" >/dev/null
git -C main-clone fetch -q "$work/out.bundle" "+$br:$br"
git -C main-clone push -q origin "$br:main"   # no --force: refused unless it fast-forwards
echo "$(date +%T) landed $br at $(git -C main-clone rev-parse --short "$br")"
```

We gave each sandbox one more small branch, both based on an old main, and started both landings at the same moment:

```bash
flock land.lock ./land.sh $A agent-e > e.log 2>&1 &
flock land.lock ./land.sh $B agent-f > f.log 2>&1 &
wait; cat f.log e.log
```

```text
11:05:50 start agent-f
OK
11:05:52 landed agent-f at 257e0a0
11:05:52 start agent-e
OK
11:05:53 landed agent-e at 5a0c928
```

Agent E's landing waited for agent F's, then rebased onto it and tested on top of it. Each landing took one to two seconds here. The test output goes to a file rather than through `| tail`, because a pipe would report `tail`'s exit code and let a failing suite land. If a rebase conflicts or a test fails, `sbx exec` exits non-zero, `set -e` stops the script, the lock is released and main is untouched. The branch goes back to its agent, as in step 2.

## What works, and what it costs

| Mitigation | What it prevents | What it doesn't | In our run |
| - | - | - | - |
| Split tasks by file or area | Textual conflicts | Semantic conflicts across files | The new test files never conflicted; agents C and D shared no file and still broke |
| Check overlap before landing (`git diff --name-only`, `git merge-tree`) | Surprise conflicts; lets you reorder | Semantic conflicts | Predicted the conflict in step 1, and called step 3 clean |
| Rebase onto current main, then test, in the agent's sandbox | Broken main from stale branches | Nothing, if every landing does it | Caught the `ImportError` the pre-rebase run missed |
| Agent resolves the conflict where it happened | Hand-resolving every conflict | Wrong resolutions, unless the tests cover the intent | Kept both changes, 4 tests green |
| One landing at a time | A race between two "tested" branches | Long queues if your tests are slow | Second landing waited about 2 s |

Splitting by file helps most when you plan the work. Before you hand out tasks, ask which files each one will touch, and give anything that touches a shared hot spot (a router, a schema, a config file) to one agent, or run it alone after the others land. Renames and signature changes are the worst offenders for semantic conflicts. Land them first and on their own, then start the other agents from the new main.

## FAQ

### Should agents merge or rebase?

Either works if you test the result. We rebased, so each branch lands as a fast-forward on top of what's already on main, and the tested commit is exactly the commit that lands. A merge commit is fine too, as long as you test the merge commit itself, not the branch.

### Can an agent resolve conflicts on its own?

Yes, in our run the scripted resolution kept both changes and passed every test. Give it the conflict and the test command, and make a green run the condition for landing. A resolution that drops one side can still pass if no test covers it, so have a person review the branch before it ships.

### Why didn't git catch the rename?

Git merges text. Agent C changed `textkit.py` and the tests; agent D added `urls.py`. No line overlapped, so git merged them cleanly. Only running the code, after combining both branches, showed that `urls.py` imported a name that no longer existed.

### How many agents can land at once?

One at a time per branch you protect, which is the point. Agents still work in parallel; only the landing step is serial. If landing becomes the bottleneck, make the tests faster or batch several branches into one tested landing.

### Where should the tests after the rebase run?

In the agent's own sandbox, as here. It already has the branch, the dependencies and the agent's context, so a failure goes straight back to the agent that can fix it.

## Related

- [Coding Agents in the Cloud: Parallel, Overnight, Own Keys, Checkpoints](/guides/coding-agents-in-the-cloud)
- [Run several coding agents in parallel, one VM each](/guides/run-coding-agents-in-parallel)
- [Git worktrees or one VM per agent?](/guides/git-worktrees-or-one-vm-per-agent)
- [Build a background coding agent that pushes a branch for review](/guides/build-a-background-coding-agent-that-pushes-a-branch-for-review)
- [Files](/docs/files)
