Running coding agents in parallel git worktrees: the setup, and the merge check git skips

This playbook runs two to four coding agents side by side, one git worktree each, and adds the check git never runs: the test suite on the merged result of every pair of agent branches, before anything lands. Worktrees keep agents from overwriting each other's files, but they cannot see two plans that contradict each other, and in a 2011 study of the Git, Perl5 and Voldemort histories, a third of all merge conflicts (133 of 399) were merges git had reported as clean that then broke the build or the tests. Every command below was run with git 2.50.1 on 24 October 2026.

What you need

• Git 2.38 or later, which added git merge-tree --write-tree.
• An agent that opens its own worktree: Claude Code 2.1.49 or later, Codex CLI 0.156.0 or later, or Cursor with its Agents Window or CLI. Plain git worktree add works with any agent.
• A test suite that runs with one command.
• Two to four tasks that change different things. Step 3 covers how to tell.

What is an intent conflict between parallel coding agents?

An intent conflict is two agents' plans contradicting each other while their diffs touch different lines, so git merges both without a word. One agent renames a function while another writes a new caller of the old name; one replaces a class while another extends it. Foremerge puts the term in its tagline, "Catch intent conflicts before code conflicts"; researchers call the same thing a semantic or higher-order conflict.

Git cannot catch it because it merges text, not meaning. The git-merge documentation says changes that do not overlap "are incorporated in the final result verbatim", and the default ort strategy is a three-way merge of hunks. For agents, CooperBench (January 2026) tagged 29.7% of failed two-agent runs as "divergent architecture": incompatible design decisions that lose work "even under a clean merge".

1. Create one worktree per agent

A git worktree is a second checkout of the same repository on its own branch, sharing one history. Create one per agent from the main checkout:

git worktree add ../shop-rename -b agent/rename
git worktree add ../shop-invoices -b agent/invoices
git worktree list

Expected output, with my paths shortened:

~/src/shop           b2cd2f4 [main]
~/src/shop-invoices  b2cd2f4 [agent/invoices]
~/src/shop-rename    b2cd2f4 [agent/rename]

Start one agent in each directory. The agents can also create the worktree themselves:

Sources: Claude Code worktrees, Codex CLI reference, Cursor worktrees and Cursor CLI. Add .claude/worktrees/ to .gitignore if you use Claude Code's flag.

2. Give each worktree its own env files, ports and database

A new worktree is a clean checkout, so gitignored files such as .env and node_modules are missing. Claude Code and the Codex desktop app copy the files listed in a .worktreeinclude file at the repository root (gitignore syntax); the Codex CLI copies nothing, so copy the files yourself:

.env
.env.local

Cursor runs commands from .cursor/worktrees.json instead, for example "setup-worktree": ["npm ci", "cp $ROOT_WORKTREE_PATH/.env .env"]. Its docs advise against symlinking dependencies into a worktree and suggest a fast package manager such as pnpm or uv instead; Orca does the opposite and shares node_modules across worktrees.

As Foremerge's author puts it, two dev servers on one port or two agents migrating one local database "collide no matter how the files are laid out", so ports and databases need splitting too. My own worktree script for Stackness gives each worktree a slot from 1 to 4, and each slot gets its own Postgres database, its own Redis database number, backend port 8088+100n and frontend port 3033+100n, written to a .wt.env file the Makefile reads. That is the move I filed for running tasks in parallel worktrees.

3. Split the tasks by contract, not by file

Two tasks are safe to run in parallel when neither one renames, replaces or removes something the other uses. Splitting by file is not enough: the conflict in step 4 comes from two branches that never touched the same line. Foremerge's author sorts the cases like this (post, 18 October 2026):

When two tasks share a contract, the same post's advice is to land the contract first: agree the interface, merge it, then start both agents from that commit.

4. Run the tests on a trial merge of every pair

The check that catches clean-but-broken merges is running the tests on the merged code, not on each branch. In my demo repository, one agent renamed get_user to fetch_user and updated every caller; the other added invoices.py, which imports get_user. Each branch passes its own tests, and git sees no conflict:

$ git merge-tree --write-tree --name-only agent/rename agent/invoices
c11c1c897c1d2ea1d46059b3745c28c257267aa3
$ echo $?
0

git merge-tree computes the merge without touching any checkout and exits 0 when it is clean. Turn that tree into a commit, check it out in a throwaway worktree and run the tests there:

TREE=$(git merge-tree --write-tree agent/rename agent/invoices) || exit 1
COMMIT=$(git commit-tree "$TREE" -p agent/rename -p agent/invoices -m "Trial merge")
git worktree add --detach ../trial "$COMMIT"
(cd ../trial && python3 -m unittest -q)
git worktree remove --force ../trial

The trial merge fails where both branches passed:

  File "~/src/trial/invoices.py", line 1, in <module>
    from users import get_user
ImportError: cannot import name 'get_user' from 'users' (~/src/trial/users.py)

Ran 2 tests in 0.001s

FAILED (errors=1)

Swap python3 -m unittest for your own install and test commands. With three agents, run it for each of the three pairs, or merge the branches one at a time and run the tests after each. Each command is documented in the git-merge-tree and git-worktree pages; I found no agent tool that runs this step for you.

curl -fsSL https://foremerge.com/install.sh | sh
foremerge init
foremerge setup all      # skill and MCP config for Claude Code, Codex and Cursor
foremerge checks set test -- cargo test --all-targets
foremerge --json intent publish --agent "$PAYPAL_AGENT" --task "add-paypal" \
  --summary "Add PayPal support to PaymentService" --scope symbol:PaymentService=extend