Short answer
A git worktree is a second working directory attached to the same repository, checked out on its own branch. Give every AI coding agent its own worktree and two agents can never overwrite the same file. The commands are git worktree add, list, remove and prune. The recurring problems are port clashes, missing node_modules and .env, disk use, losing track of which directory is which, and rebases. Claude Code, Codex and Cursor can create worktrees for you; Orchestrator.inc (formerly Agent Orchestrator) also handles setup, PR feedback and cleanup. Do it by hand if you run two or three agents; use a manager if you run more.
What a worktree is
A normal clone has one working directory and one checked-out branch. git worktree lets one .git directory serve several working directories at once, each on a different branch, sharing objects and refs. There is no second clone and no duplicate history, and a commit made in one worktree is visible from the others immediately. Git refuses to check out the same branch in two worktrees, which is exactly the guarantee you want when agents run in parallel.
Why each agent needs its own
Agents do not take turns. They read, think and write on their own clocks. Put two of them in one directory and sooner or later both edit the same file, and one set of changes is lost or the file ends up half of each. A worktree per task fixes that and gives you two more things:
- a clean
git statusper agent, so its commits contain only its own changes - a branch per task, so one PR maps to one agent
The manual way
# create a worktree one directory up, on a new branch
git worktree add ../project-feature-a -b feature-a
# start your agent inside it
cd ../project-feature-a && claude
# see every worktree, its path, HEAD and branch
git worktree list
# remove one when the branch is merged (refuses if it has uncommitted changes)
git worktree remove ../project-feature-a
# clean up metadata for directories you deleted by hand
git worktree prune
Repeat in a second terminal for a second agent. Pair it with tmux or terminal tabs and you have a free, vendor-neutral setup that works with any agent. For a full walkthrough, see how to run multiple Claude Code agents in parallel.
The recurring problems
| Problem | What happens | Fix by hand |
|---|---|---|
| Ports | The second worktree's dev server tries the same port as the first and fails | A per-worktree PORT variable |
| node_modules and .env | A fresh worktree has neither, so the build fails and the agent spends context diagnosing it | Copy .env; reinstall or symlink node_modules |
| Disk | Each worktree with its own installed dependencies adds up quickly on a large repo | Share caches; delete merged worktrees |
| Which is which | Several terminals look identical, and a dozen directories give no hint which branches were merged | A naming scheme and notes |
| Rebases | Each merge into main may mean the other branches need a rebase | Rebase and resolve by hand |
Ports
Give each worktree its own port through an environment variable and have your dev server read it. Printing the port in the terminal title helps you match a browser tab to an agent.
PORT=3101 npm run dev # worktree A
PORT=3102 npm run dev # worktree B
Dependencies and .env
Gitignored files do not come along with git worktree add. Copy .env into each new worktree, or symlink it if every branch uses the same values. Share node_modules with a symlink only when the lockfile is the same across branches; otherwise reinstall.
Cleanup
Commit or stash before git worktree remove. It refuses dirty trees, which is a feature. Run git worktree prune after deleting directories by hand, or git worktree add will complain about stale entries. Delete merged worktrees regularly; disk, not CPU, is usually what runs out.
How agent vendors handle it
As of October 2026, Claude Code, Codex and Cursor each create worktrees in their own way.
Claude Code. claude --worktree <name> (or -w) creates .claude/worktrees/<name>/ on its own branch, based on the remote default branch by default. A .worktreeinclude file lists gitignored files such as .env to copy in. Clean worktrees are removed on exit and dirty ones prompt. Agent teams share one checkout rather than one worktree each.
Codex. The desktop app has Local, Worktree and Cloud modes for a chat. Worktree mode checks out under the Codex home directory in detached HEAD, you can create a branch from there, and .worktreeinclude works the same way. Worktrees are a desktop app feature, not a CLI one.
Cursor. The IDE offers /worktree and related commands, the Agents Window has native worktrees, and the CLI accepts --worktree.
All three solve creation for their own agent. None gives you one view of worktrees across vendors, follows the PR each one opened, or tells you which are safe to delete.
Manual versus managed
Manual (git worktree plus tmux) | Agent vendor tools | Orchestrator.inc | |
|---|---|---|---|
| Create | You run the command | Automatic | Automatic |
| Branch | Whatever you type | Remote default (Claude Code), detached HEAD (Codex) | A new branch per session |
| Dependencies and .env | Copy by hand | .worktreeinclude for files; ask the agent to install | postCreate, symlinks and env per project |
| Ports | You set them | You set them | Project environment variables |
| Multi-repo | You manage it | Not documented | Multi-repo workspaces |
| Which is which | Memory | The vendor's sidebar, one vendor | One board across 38 harnesses |
| PR, CI, review | You watch them | A PR label or status bar | Sent to the worktree's session |
| Cleanup | remove and prune | Varies by vendor | ao session cleanup, skips dirty worktrees |
Doing this with Orchestrator.inc
Everything above works, and for two or three agents it is all you need. Past that, the bookkeeping is the job. Orchestrator.inc does the same steps for you:
- Add a project once, in the desktop app or with the
aoCLI. - Start a session with
ao spawnor New session, and pick any of the 38 harnesses. The local daemon creates a worktree under~/.aoon its own branch (worktree docs). - Setup runs for you. Per-project
postCreatecommands install dependencies or generate code,symlinksshare paths such asnode_modulesand.env, and project environment variables pass in settings such as the port your dev server reads. A setup script and a cleanup script can run as well. - Multi-repo and scratch work. A workspace can span several repositories. A standalone worker with no project gets a managed directory with no branch. Sessions can also run on your own server or cloud VM: install Orchestrator's host there and start and supervise them from the same desktop app.
- Which is which. The Kanban board shows every worktree as a session card in Working, Needs you, In review or Ready to merge, placed by session, PR, CI and review facts.
- After the PR opens, failing checks, review comments and merge conflicts go to the session that owns that worktree, so the agent can fix, respond or rebase.
- Cleanup.
ao session cleanup --dry-runlists what would be removed, and the real run skips worktrees with uncommitted changes so nothing is lost.
Orchestrator runs on macOS, Windows and Linux. Running Orchestrator on your own machines is free and open source (Apache-2.0), with no account needed; you bring your own agent subscriptions or API keys. Optional Orchestrator Cloud plans, for agents that keep working while your laptop is closed, are Starter at $20/month and Pro at $40/month, with Enterprise pricing on request. To try it, follow the quickstart and spawn two agents on the same repository. For a side-by-side with Claude Code's own tooling, see Orchestrator.inc vs Claude Code's built-in worktrees.
Frequently Asked Questions
What are git worktrees for AI coding agents?
A git worktree is an extra working directory on its own branch that shares one repository. Giving each AI coding agent its own worktree means agents can work in parallel without editing the same files, and each agent's commits and PR stay separate.
Does a git worktree copy the whole repository?
No. Worktrees share one object database and refs, so only the checked-out files are written. Installed dependencies are usually the real disk cost, since each worktree may get its own copy.
Can two worktrees check out the same branch?
No. Git refuses, which stops two agents from committing to the same branch. Create a branch per task when you add the worktree, or let your tool name one for you.
Does .env come along in a new worktree?
Not by itself, because it is gitignored. Claude Code and Codex read a worktreeinclude file that lists gitignored paths to copy. Orchestrator.inc uses per-project symlinks and environment settings, so the file is shared rather than copied.
Is a worktree a security sandbox?
No. It is development isolation on the same machine under the same user, and an agent can still read other directories. If you need a hard boundary, use a container or a cloud session, and keep a worktree per task inside it.
How do I clean up worktrees safely?
By hand, run git worktree remove on each merged worktree, then git worktree prune. In Orchestrator.inc, run ao session cleanup with the dry-run flag to preview, then run it for real; worktrees with uncommitted changes are left alone. The worktree guide at docs.orchestrator.inc covers the settings.