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

A playbook for running two to four coding agents in parallel git worktrees adds a merge check git does not perform: running the test suite on the merged result of every pair of agent branches before anything lands. The playbook, run with git 2.50.1 on 24 October 2026, cites a 2011 study of the Git, Perl5 and Voldemort histories in which 133 of 399 merge conflicts — a third — were merges git reported as clean that then broke the build or tests, and CooperBench (January 2026) tagged 29.7% of failed two-agent runs as "divergent architecture." The setup requires git 2.38 or later for `git merge-tree --write-tree` and an agent that opens its own worktree, such as Claude Code 2.1.49 or later, Codex CLI 0.156.0 or later, or Cursor's Agents Window or CLI.

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 https://homes.cs.washington.edu/~mernst/pubs/vc-conflicts-fse2011.pdf 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 https://stackness.dev/tools/git 2.38 or later, which added git merge-tree --write-tree . - An agent that opens its own worktree: Claude Code https://stackness.dev/tools/claude-code 2.1.49 or later, Codex CLI https://stackness.dev/tools/codex-cli 0.156.0 or later, or Cursor https://stackness.dev/tools/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 https://stackness.dev/tools/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 https://git-scm.com/docs/git-merge 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 https://arxiv.org/abs/2601.13295 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: | Agent | Command | Where the worktree goes | Since | |---|---|---|---| | Claude Code | claude --worktree feature-auth | .claude/worktrees/feature-auth/ , branch worktree-feature-auth | v2.1.49, 19 February 2026 | | Codex CLI | codex exec --worktree "..." or /worktree | managed by Codex | default since 0.156.0, 22 September 2026 | | Cursor CLI | agent --worktree auth-fix "..." | ~/.cursor/worktrees/<repo /auth-fix | not stated in the docs | Sources: Claude Code worktrees https://code.claude.com/docs/en/worktrees , Codex CLI reference https://developers.openai.com/codex/cli/reference , Cursor worktrees https://cursor.com/docs/configuration/worktrees and Cursor CLI https://cursor.com/docs/cli/using . 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 https://stackness.dev/tools/pnpm or uv https://stackness.dev/tools/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 https://stackness.dev/moves/git-worktrees-for-parallel-task-execution . 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 https://dev.to/naw103/running-multiple-claude-code-agents-in-parallel-what-worktrees-cannot-see-4le7 : | What the two agents do | What git does | What breaks | |---|---|---| | Edit the same lines | conflict | nothing silent | | Rename vs a new call to the old name | clean merge | the build | | Replace vs extend | clean merge | the design | | Change a schema or config vs code against the old shape | clean merge | runtime | 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: bash $ 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: python 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 https://git-scm.com/docs/git-merge-tree and git-worktree https://git-scm.com/docs/git-worktree pages; I found no agent tool that runs this step for you. 5. Declare intents before the agents edit, with Foremerge Foremerge moves the check before the code exists: each agent publishes what it plans to change and how, and Foremerge flags plans that clash. It is Apache-2.0, written in Rust, at version 0.5.1 since 3 October 2026, with 520 GitHub stars on 24 October. Its author, Nick Woodhead, founded it and uses it at his other company, so every claim about how well it works is his own. 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 When another agent has published symbol:PaymentService=replace , Foremerge reports a HIGH conflict before either agent writes code: Foremerge 0.1.0 demo from the Foremerge README https://github.com/naw103/foremerge by Nick Woodhead, Apache-2.0. Since 0.4.0 the finding is named destructive vs additive . By default Foremerge stores everything in one SQLite file at <git-common-dir /foremerge/state.sqlite3 , which every worktree of the repository shares. Its conflict check compares only what agents declare, not diffs, call graphs or a syntax tree, and its README says "Published benchmark results do not yet exist". Its acceptance check runs your tests on one branch at a time, not on the merged pair, a gap the author has logged as an open item https://github.com/naw103/foremerge/discussions/32 . Step 4 still applies. Coordination layers above git, and what each one stores Four tools besides Foremerge claim a layer above git for parallel agents, and they store very different things: | Tool | What it stores | Works with | Latest release | |---|---|---|---| | Foremerge https://stackness.dev/tools/foremerge | declared intents, claims and test results in SQLite in the git common directory | Claude Code, Codex, Cursor | 0.5.1, 3 Oct 2026 | | Spec Kitty https://stackness.dev/tools/spec-kitty | spec, plan and work packages with owned files under kitty-specs/ , plus lanes.json | Claude, Codex, Cursor and others | 3.2.7, 9 Sep 2026 | | agent-coord https://stackness.dev/tools/agent-coord | file and port leases, messages and decisions in SQLite under ~/.agent-coord , machine-wide | Claude Code and Codex hooks, any git commit | 1.9.1, 10 Sep 2026 | | Clash https://stackness.dev/tools/clash | nothing; runs git merge-tree across every worktree pair, so it sees textual conflicts only | Claude Code hook, any CLI | 0.2.0, 8 Feb 2026 | | Orca https://stackness.dev/tools/orca | worktrees and orca.yaml ; no conflict detection documented | many agents | 1.4.239, 24 Oct 2026 | Spec Kitty https://github.com/spec-kitty/spec-kitty prevents conflicts at planning time: work packages whose owned files overlap go into the same lane and run one after another. That is ownership by file, so a rename that breaks a caller in another file still gets through. Orca and six other fleet consoles are compared in seven ways to manage several coding agents https://stackness.dev/blog/manage-multiple-coding-agents-from-one-workspace-orca-offrun-pi-pod-and-four-other-options-compared , and an agent filesystem in place of worktrees in the LayerFS post https://stackness.dev/blog/layerfs-ai-coding-agents-what-it-adds-over-git-worktrees . What goes wrong fatal: 'agent/rename' is already used by worktree Git checks out a branch in one worktree at a time, so git worktree add ../shop-again agent/rename fails with fatal: 'agent/rename' is already used by worktree at '~/src/shop-rename' . Give every agent a new branch with -b . The trial worktree refuses to delete git worktree remove ../trial failed in my run with contains modified or untracked files, use --force to delete it , because the test run left pycache behind. Use --force for throwaway worktrees only, and git worktree prune after deleting a worktree directory by hand. Two agents pick the same new ID Both of my worktree merges into Stackness on 9 and 10 October 2026 merged a new end-to-end test scenario numbered the same as one the other branch had added. Git saw two different files and no conflict. Anything numbered sequentially migrations, task IDs, test IDs needs a renumbering step at merge time, or IDs that cannot collide. When is running agents in parallel not worth the review cost? Parallel agents stop paying when their tasks share a contract, because the coordination then costs more than the time saved. In CooperBench, two agents splitting a pair of features succeeded about 30% less often than one agent doing both, and on a 46-task subset, success fell from 68.6% with two agents to 46.5% with three and 30.0% with four. Cursor reported in February 2026 https://cursor.com/blog/self-driving-codebases that with locks on a shared file, "20 agents would slow to the throughput of 1-3". The other side has numbers too. When tasks are split along the code's dependency graph, Co-Coder https://arxiv.org/abs/2606.00953 measured up to 2.10x faster runs and up to 35% lower API cost on 28 tasks. The rule I follow: parallel for tasks that touch different contracts, one at a time for anything that renames, replaces or removes. Every extra agent branch is one more diff to read, which is the review bottleneck https://stackness.dev/blog/how-much-human-code-review-ai-generated-code-needs-claude-code-numbers under another name. Checklist - Git 2.38 or later; one worktree and one new branch per agent - .worktreeinclude , .cursor/worktrees.json or a script copies the env files - Each worktree has its own ports and database - No two parallel tasks rename, replace or remove the same contract - Tests pass on a trial merge of every pair before anything lands - Sequential IDs and migrations renumbered at merge time - Throwaway worktrees removed, git worktree prune run The setup is the git worktrees for parallel task execution move https://stackness.dev/moves/git-worktrees-for-parallel-task-execution , and the terminal and shell tools developers pair with it https://stackness.dev/categories/terminal-shell are on Stackness. New posts by email About one email a week with what we published. No account needed. Which of these do you use? Nobody on Stackness runs Foremerge yet. Tick what you use and be the first. Play Lonny Eagle Amateur Skater 4A pixel art skateboarding game. Signing up opens it straight away.Sign up to play https://stackness.dev/games/lonny-eagle