Two agents can edit one repository at the same time without trampling each other if each gets its own working directory. Git already has that: git worktree. The rest of this post is the workflow around it, with commands I ran in a throwaway repo on 2026-10-23 (git 2.43.0, Linux) and the places where it still goes wrong.
It's agent-neutral. Claude Code and Codex CLI both have worktree flags now, covered below, but everything else works with any tool that edits files in a directory. For the agents themselves, see our Claude Code best practices checklist and Codex CLI best practices.
How do I give each agent its own worktree?
One task, one branch, one worktree, one agent. That's the pattern practitioner write-ups keep converging on (for example OpenReplay's guide, which I only saw through a search summary, so treat it as a practitioner opinion, not something I verified). Here it is with real output.
git worktree add ../demo-wt/agent-a -b agent/a-greet-polite
git worktree add ../demo-wt/agent-b -b agent/b-total-validate
git worktree list
Preparing worktree (new branch 'agent/a-greet-polite')
HEAD is now at bc746f7 initial
Preparing worktree (new branch 'agent/b-total-validate')
HEAD is now at bc746f7 initial
/tmp/r3e/demo bc746f7 [main]
/tmp/r3e/demo-wt/agent-a bc746f7 [agent/a-greet-polite]
/tmp/r3e/demo-wt/agent-b bc746f7 [agent/b-total-validate]
Then start one agent per directory, each in its own terminal: cd ../demo-wt/agent-a and launch your tool there. Put worktrees outside the repo (a sibling folder) so editors and file watchers on the main checkout don't index them. If you prefer them inside the repo, add the folder to .gitignore.
Both tools can create the worktree for you:
- Claude Code:
claude --worktree feature-auth(or-w). Per Anthropic's worktrees docs, it creates.claude/worktrees/<name>/on a new branch namedworktree-<name>. It branches from the repository's default branch by default; setworktree.baseRefto"head"in settings to branch from your current local HEAD instead. - Codex CLI:
codex --worktreeappears incodex --helpon 0.164.0 ("Run the session in a new managed Git worktree"). I read the help text only and did not run it, so I can't tell you where it puts the directory or how it names the branch.
I still use plain git worktree add when I want control over branch names, as in the next section.
What branch naming makes review easier?
Prefix by who made it, then say what it does: agent/a-greet-polite. In git branch --list 'agent/*' you instantly see every pending agent branch, and git branch -d cleanup is a one-liner pattern. Include the task in the name, not just a number, because three weeks later "agent-2" means nothing. If the tool names the branch itself (Claude Code uses worktree-<name>), pass a meaningful <name>.
What does a worktree not carry over?
Three things bite on day one.
Gitignored files. I put a .env in the main checkout and listed the new worktree:
.
..
.git
.gitignore
app.py
No .env. A worktree is a fresh checkout of tracked files. Claude Code's docs describe a .worktreeinclude file at the project root (gitignore syntax) that copies matching gitignored files into worktrees Claude creates. With plain git, copy them in a setup script.
Installed dependencies. node_modules/ or a virtualenv don't exist in the new directory. Budget the install time, or use a package manager with a shared cache.
Shared runtime state. Two dev servers both want port 3000, and two test runs may share one local database. One guide I found flagged ports and databases as things to manage across worktrees, not only files (a search-summary claim, but it matches how this fails in practice). Give each worktree its own port and database name through env vars.
Git also protects you from one mistake. Checking out a branch that another worktree holds fails:
fatal: 'agent/a-greet-polite' is already used by worktree at '/tmp/r3e/demo-wt/agent-a'
How do I merge parallel agent work?
Review each branch before it touches main. My flow:
- Agent finishes; you run its tests inside its worktree.
git diff main...agent/a-greet-polite --statto check scope.- Merge into main one branch at a time, rerunning tests after each.
When the agents touched different regions, git merges them cleanly. This is what I ran, after each agent committed in its own worktree:
$ git merge --no-ff -m 'merge agent A' agent/a-greet-polite
Merge made by the 'ort' strategy.
app.py | 2 +-
$ git merge --no-ff -m 'merge agent B' agent/b-total-validate
Auto-merging app.py
Merge made by the 'ort' strategy.
app.py | 2 +-
Agent A rewrote greet, agent B changed total, same file, no conflict. The merged file had both changes.
Clean merge does not mean correct merge. Two agents can make individually fine edits that break each other semantically (one renames a function, the other adds a call to the old name). Run the full test suite after the last merge, not just each agent's own tests.
What happens when two agents touch the same lines?
I made two branches from the same commit, one rewriting greet to a polite greeting and one to an uppercase shout, then merged both. First, a dry run that doesn't touch the working tree (git merge-tree --write-tree needs a recent git; mine was 2.43.0):
$ git merge-tree --write-tree --name-only main agent/c-shout
404aa44a179661df9692305bd586bdf2c546de2b
app.py
Auto-merging app.py
CONFLICT (content): Merge conflict in app.py
(exit status 1)
Then the real merge:
$ git merge agent/c-shout
Auto-merging app.py
CONFLICT (content): Merge conflict in app.py
Automatic merge failed; fix conflicts and then commit the result.
$ git status --short
UU app.py
def greet(name):
<<<<<<< HEAD
return "Hello, " + name + "!"
=======
return ("HELLO " + name).upper()
>>>>>>> agent/c-shout
git merge --abort returned me to a clean tree. Your options when this happens, in order of preference:
- Abort, then ask the second agent to rebase onto the updated main and redo its change given the first one (
git rebase maininside its worktree, or restate the task). The agent knows its intent better than you do. - Resolve by hand if it's a few lines.
- Throw one branch away. Agent work is cheap; your review time isn't.
Run merge-tree as a pre-check on every branch before you commit to a merge order. It's a free conflict forecast.
How do I clean up?
$ git worktree remove ../demo-wt/agent-a
$ git branch -d agent/a-greet-polite
Deleted branch agent/a-greet-polite (was 30373b3).
Git protects unsaved work. Removing a worktree with an untracked file is refused:
fatal: '../demo-wt/agent-d' contains modified or untracked files, use --force to delete it
A locked worktree refuses removal too (cannot remove a locked working tree; use 'remove -f -f' to override or unlock first). Claude Code takes such a lock while an agent runs, per its docs, and for -p runs it doesn't clean up the worktree at all, so git worktree remove is yours to run. Use git worktree prune for entries whose directory is already gone. git branch -d also refuses unmerged branches, which is the safety net you want: use -D only on purpose.
How many agents can my machine run?
The honest answer is to measure, not guess. My scratch box reported nproc of 4. Each agent mostly waits on the model, so the agents themselves are light; the load comes from what they run: installs, test suites, type checkers, dev servers, browsers. Four agents each running a full test suite on four cores will crawl and fail timeouts that have nothing to do with the code.
Limits that help:
- Cap concurrency of the heavy step, not the agents (for example one shared lock around the full test suite).
- Ask agents to run the single relevant test file, not everything, until the end.
- Watch memory first. If a dev server plus tests needs 2 GB, three agents need about 6 GB before your editor starts.
- Cost scales too. Every extra agent is another set of requests against your plan or API balance.
When do parallel agents backfire?
- Overlapping files. Two agents "adding a feature" in the same module will conflict. Split by file or layer, or run them in sequence.
- Dependent tasks. If task B needs task A's API, B guesses and guesses wrong. Sequence them.
- Review debt. Three finished branches waiting is not a speedup if you merge them unread. The practitioner write-ups I saw agree gains come from throughput across tasks, not speed on any one, and that merge coordination becomes the bottleneck (search summaries of vendor and individual blogs, so anecdotes, not benchmarks).
- Shared state. A migration in one branch changes the database the others test against.
- Tiny tasks. Setting up a worktree and installing dependencies costs more than a one-line fix. Do those in place.
A rule I'd adopt: before launching agent N+1, ask whether you could review N+1 results today. If not, wait.
Keeping agents running while you're away
Parallel agents work best on a machine that stays on, so runs don't die when your laptop sleeps. Our persistent remote dev box guide covers tmux on a VPS. If you go that route, size for memory, since parallel test runs eat RAM; a 2 vCPU, 8 GB plan like Hostinger's KVM 2 is the minimum I'd consider for two or three agents, based on the memory arithmetic above, not a benchmark. Non-affiliate alternatives: any other VPS provider, a cloud VM from AWS, Google Cloud or Azure, or a spare machine at home.
Disclosure: the Hostinger link below is an affiliate link. I may earn a commission if you buy through it, at no cost to you. Hostinger KVM 2
