{"slug": "running-coding-agents-in-parallel-git-worktrees-the-setup-and-the-merge-check", "title": "Running coding agents in parallel git worktrees: the setup, and the merge check git skips", "summary": "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.", "body_md": "# Running coding agents in parallel git worktrees: the setup, and the merge check git skips\n\nThis 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.\n\n## What you need\n\n- [Git](https://stackness.dev/tools/git) 2.38 or later, which added`git merge-tree --write-tree` .\n- 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.\n- A test suite that runs with one command.\n- Two to four tasks that change different things. Step 3 covers how to tell.\n\n## What is an intent conflict between parallel coding agents?\n\nAn 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.\n\nGit 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\".\n\n## 1. Create one worktree per agent\n\nA 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:\n\n```\ngit worktree add ../shop-rename -b agent/rename\ngit worktree add ../shop-invoices -b agent/invoices\ngit worktree list\n```\n\nExpected output, with my paths shortened:\n\n```\n~/src/shop           b2cd2f4 [main]\n~/src/shop-invoices  b2cd2f4 [agent/invoices]\n~/src/shop-rename    b2cd2f4 [agent/rename]\n```\n\nStart one agent in each directory. The agents can also create the worktree themselves:\n\n| Agent | Command | Where the worktree goes | Since | \n|---|---|---|---|\n| Claude Code | `claude --worktree feature-auth` | `.claude/worktrees/feature-auth/` , branch`worktree-feature-auth` | v2.1.49, 19 February 2026 | \n| Codex CLI | `codex exec --worktree \"...\"` or`/worktree` | managed by Codex | default since 0.156.0, 22 September 2026 | \n| Cursor CLI | `agent --worktree auth-fix \"...\"` | `~/.cursor/worktrees/<repo>/auth-fix` | not stated in the docs | \n\nSources: [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.\n\n## 2. Give each worktree its own env files, ports and database\n\nA 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:\n\n```\n.env\n.env.local\n```\n\nCursor 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.\n\nAs 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).\n\n## 3. Split the tasks by contract, not by file\n\nTwo 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)):\n\n| What the two agents do | What git does | What breaks | \n|---|---|---|\n| Edit the same lines | conflict | nothing silent | \n| Rename vs a new call to the old name | clean merge | the build | \n| Replace vs extend | clean merge | the design | \n| Change a schema or config vs code against the old shape | clean merge | runtime | \n\nWhen 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.\n\n## 4. Run the tests on a trial merge of every pair\n\nThe 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:\n\n``` bash\n$ git merge-tree --write-tree --name-only agent/rename agent/invoices\nc11c1c897c1d2ea1d46059b3745c28c257267aa3\n$ echo $?\n0\n```\n\n`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:\n\n```\nTREE=$(git merge-tree --write-tree agent/rename agent/invoices) || exit 1\nCOMMIT=$(git commit-tree \"$TREE\" -p agent/rename -p agent/invoices -m \"Trial merge\")\ngit worktree add --detach ../trial \"$COMMIT\"\n(cd ../trial && python3 -m unittest -q)\ngit worktree remove --force ../trial\n```\n\nThe trial merge fails where both branches passed:\n\n``` python\n  File \"~/src/trial/invoices.py\", line 1, in <module>\n    from users import get_user\nImportError: cannot import name 'get_user' from 'users' (~/src/trial/users.py)\n\nRan 2 tests in 0.001s\n\nFAILED (errors=1)\n```\n\nSwap `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.\n\n## 5. Declare intents before the agents edit, with Foremerge\n\nForemerge 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.\n\n```\ncurl -fsSL https://foremerge.com/install.sh | sh\nforemerge init\nforemerge setup all      # skill and MCP config for Claude Code, Codex and Cursor\nforemerge checks set test -- cargo test --all-targets\nforemerge --json intent publish --agent \"$PAYPAL_AGENT\" --task \"add-paypal\" \\\n  --summary \"Add PayPal support to PaymentService\" --scope symbol:PaymentService=extend\n```\n\nWhen another agent has published `symbol:PaymentService=replace`, Foremerge reports a HIGH conflict before either agent writes code:\n\n*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`.*\n\nBy 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.\n\n## Coordination layers above git, and what each one stores\n\nFour tools besides Foremerge claim a layer above git for parallel agents, and they store very different things:\n\n| Tool | What it stores | Works with | Latest release | \n|---|---|---|---|\n| [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 | \n| [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 | \n| [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 | \n| [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 | \n| [Orca](https://stackness.dev/tools/orca) | worktrees and `orca.yaml` ; no conflict detection documented | many agents | 1.4.239, 24 Oct 2026 | \n\n[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).\n\n## What goes wrong\n\n### fatal: 'agent/rename' is already used by worktree\n\nGit 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`.\n\n### The trial worktree refuses to delete\n\n`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.\n\n### Two agents pick the same new ID\n\nBoth 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.\n\n## When is running agents in parallel not worth the review cost?\n\nParallel 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\".\n\nThe 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.\n\n## Checklist\n\n- Git 2.38 or later; one worktree and one new branch per agent\n- `.worktreeinclude` ,`.cursor/worktrees.json` or a script copies the env files\n- Each worktree has its own ports and database\n- No two parallel tasks rename, replace or remove the same contract\n- Tests pass on a trial merge of every pair before anything lands\n- Sequential IDs and migrations renumbered at merge time\n- Throwaway worktrees removed, `git worktree prune` run\n\nThe 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.\n\n## New posts by email\n\nAbout one email a week with what we published. No account needed.\n\n## Which of these do you use?\n\nNobody on Stackness runs Foremerge yet. Tick what you use and be the first.\n\n[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)", "url": "https://wpnews.pro/news/running-coding-agents-in-parallel-git-worktrees-the-setup-and-the-merge-check", "canonical_source": "https://stackness.dev/blog/running-coding-agents-in-parallel-git-worktrees-and-the-merge-check", "published_at": "2026-10-24 13:56:22+00:00", "updated_at": "2026-10-24 14:44:01.000336+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Git", "Claude Code", "Codex CLI", "Cursor", "CooperBench", "Foremerge", "Perl5", "Voldemort"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/running-coding-agents-in-parallel-git-worktrees-the-setup-and-the-merge-check", "markdown": "https://wpnews.pro/news/running-coding-agents-in-parallel-git-worktrees-the-setup-and-the-merge-check.md", "text": "https://wpnews.pro/news/running-coding-agents-in-parallel-git-worktrees-the-setup-and-the-merge-check.txt", "jsonld": "https://wpnews.pro/news/running-coding-agents-in-parallel-git-worktrees-the-setup-and-the-merge-check.jsonld"}}