Git worktrees give each agent a separate checkout, HEAD, and staging index. They share the repository's objects and branch references, so agents can edit in parallel without overwriting each other's files, then hit a normal Git merge conflict when their branches meet.
What Git worktrees separate
A linked worktree is a second checkout attached to one repository. Git gives it a separate directory for project files and private administrative files under .git/worktrees/<id>/. The linked worktree has its own HEAD and index, so an agent can edit, stage, commit, or leave changes in its checkout without changing another worktree's files or staging area.
The repository does not get a second copy of its history. Git shares the object database and the ordinary refs/ namespace across worktrees. A commit made in one worktree is therefore available to the others, even though the checked-out files differ.
What Git worktrees still share
The branch namespace is shared. By default, git worktree add refuses to check out a branch that another worktree already uses. Give each task a distinct branch, or use --detach when a task should point at a commit without claiming a branch. Detached HEAD is a Git option; it is not evidence that every agent tool uses that mode.
Git worktrees also do not sandbox processes or shared services. Superset's worktree guide says that two development servers may request the same port, tests may write to the same database, and an agent with access to other directories or services can affect them. A tool can add controls around Git. Superset documents preview ports per workspace, and Paseo assigns a distinct $PASEO_PORT to its managed services. Those controls belong to the orchestrator, not to Git worktrees.
A fresh worktree also does not carry over ignored files by itself. In the reproduction for this post, .env existed in the main checkout but was missing from both agent worktrees. Treat secrets, dependencies, caches, ports, and test data as separate setup concerns.
Why a merge conflict waits
Two worktrees can start from the same commit and change the same line without touching each other's files:
git worktree add -b agent-feature-a ../agent-a main
git worktree add -b agent-feature-b ../agent-b main
# Each agent edits app.js and commits its own branch.
git merge agent-feature-a --no-edit
git merge agent-feature-bThe first merge can fast-forward. The second merge can stop with:
Auto-merging app.js
CONFLICT (content): Merge conflict in app.js
Automatic merge failed; fix conflicts and then commit the result.That is the boundary worktrees cannot move. They prevent simultaneous writes to one checkout. Git's merge machinery still compares the two branch tips with their common ancestor, and overlapping edits may need a human or an agent to choose the result. The reproduction's full command and output are in artifacts/snippets/01-reproduce-worktree-conflict.sh and artifacts/logs/13-worktree-conflict-demo.txt.
What agent tools add around Git worktrees
The products in this post add setup and supervision around the Git primitive:
Tool | Verified behavior on 2026-10-06 |
|---|---|
Superset | Gives each task a Git worktree with its own branch and terminals. Its README says, "Worktrees separate working files; they do not sandbox processes or prevent merge conflicts." |
Orca | Gives each worktree its own branch, files, and agent terminals. |
Paseo | Creates a separate directory and branch, runs setup and teardown hooks, and assigns service ports through |
Firstmate | Runs each task in a clean Treehouse worktree, or an Orca worktree when |
Codex app | OpenAI documents built-in worktree support and an isolated copy of the code for each agent. |
These features solve different problems. Git supplies checkout and merge semantics. The surrounding tool decides how to copy .env, install dependencies, allocate ports, watch an agent, or deliver a branch for review.
A practical boundary for parallel agents
Use one worktree per task and give each task a unique branch unless detached HEAD is intentional. Recreate ignored configuration and dependencies before the agent runs. Allocate service ports and test data outside Git. Then merge branches one at a time, resolve any conflicts, and run the combined tests.
Worktrees change a file-overwrite problem into a visible integration step. They do not remove the integration step.
Sources
- Git worktree reference: https://git-scm.com/docs/git-worktree (read 2026-10-06)
- Git merge reference: https://git-scm.com/docs/git-merge (read 2026-10-06)
- Superset README: https://raw.githubusercontent.com/superset-sh/superset/main/README.md (read 2026-10-06)
- Superset worktree guide: https://github.com/superset-sh/superset/blob/main/apps/marketing/content/blog/working-with-worktrees-in-superset.mdx (read 2026-10-06)
- Orca worktree documentation: https://www.onorca.dev/docs/model/worktrees (read 2026-10-06)
- Paseo worktree documentation: https://paseo.sh/docs/worktrees (read 2026-10-06)
- Firstmate README: https://raw.githubusercontent.com/kunchenguid/firstmate/main/README.md (read 2026-10-06)
- OpenAI Codex worktree documentation: https://developers.openai.com/codex/app/worktrees/ (read 2026-10-06)
- Freshness corroboration: https://nimbalyst.com/blog/best-git-worktree-tools-ai-coding-2026/ (read 2026-10-06)
Last verified: 2026-10-06.