A git worktree is a second working directory attached to the same repository, checked out on its own branch. Give each coding agent task its own worktree with git worktree add -b <branch> <path> <base> and two agents can edit the same repo at the same time without touching each other's files or yours.
Every command here was run on git 2.50 before I wrote it down. The reference is the git-worktree manual.
Why do coding agents need worktrees?
An agent edits files and runs tests in a directory. Put two agents in one directory and each sees the other's half-finished edits, the tests fail for reasons neither caused, and both try to fix it. Cloning the repo twice works but doubles the history on disk and leaves you pushing and pulling between your own clones. Worktrees share one object store and one set of branches, so a commit made in one is visible from all of them at once.
The five commands
| Command | What it does |
|---|---|
git worktree add -b agent/fix-login ../app-fix-login main | Creates the branch agent/fix-login from main and checks it out at ../app-fix-login |
git worktree add ../app-review agent/fix-login | Checks out an existing branch in a new worktree |
git worktree list | Lists every worktree with its commit and branch; the main one comes first |
git worktree remove ../app-fix-login | Deletes a clean worktree. The branch stays. |
git worktree prune | Forgets worktrees whose folders were deleted by hand |
A full round for one task:
cd ~/code/app
git worktree add -b agent/fix-login ../app-fix-login main
cd ../app-fix-login
npm ci # a worktree has no node_modules yet
claude # or: codex
# later, from ~/code/app, once the branch is merged
git worktree remove ../app-fix-login
git branch -d agent/fix-loginIf you leave out -b, git names the branch after the last part of the path: git worktree add ../hotfix creates a branch called hotfix. I always pass -b and a base so the result does not depend on where I happened to be standing.
Where should the worktrees live?
There are two layouts, and both are fine.
Siblings of the repo. ~/code/app, ~/code/app-fix-login, ~/code/app-csv-export. Nothing to ignore, and editors treat each as a separate folder. The cost is a crowded parent directory.
A folder inside the repo. ~/code/app/.worktrees/fix-login, with .worktrees/ in .gitignore. Everything stays under one root. The cost is that search tools and file watchers in the main checkout may walk into the worktrees unless you exclude the folder.
Name the folder and the branch after the task. Three weeks later, agent/fix-login-redirect tells you what it was. wt3 does not.
What do Claude Code and Codex do on their own?
Claude Code has a flag for this. claude --worktree fix-login (or -w) creates the worktree under .claude/worktrees/fix-login/ on a branch named worktree-fix-login, and starts the session there. By default it branches from the repo's default branch on the remote, not from your local HEAD. When you exit an interactive session, Claude Code checks the worktree: a clean one from an unnamed session is removed, and otherwise it asks whether to keep it. Details are in Anthropic's worktrees documentation.
Codex CLI 0.159.0 lists an experimental --worktree flag in codex --help, described as running the session in a new managed git worktree. I mostly create the worktree myself and start Codex inside it, because then both agents follow the same layout.
The pitfalls
The stash is shared. All worktrees share one stash. Run git stash in a worktree, then git stash list in the main checkout, and the entry is there. An agent that runs git stash pop to tidy up can apply another task's changes to its own branch. Tell agents not to stash. Have them commit work in progress on their own branch instead.
Ignored files do not come along. A worktree contains tracked files only. .env, .env.local, local certificates and anything else in .gitignore are missing, and the app fails to start for a reason the agent will spend twenty turns investigating. Copy them as part of creating the worktree:
git worktree add -b agent/fix-login ../app-fix-login main
cp .env .env.local ../app-fix-login/For worktrees that Claude Code creates, a .worktreeinclude file at the repo root does the same job. It uses .gitignore syntax and only copies files that are also gitignored.
Dependencies are installed once per worktree. node_modules, virtualenvs and build output are untracked, so every worktree starts without them. That means an install per task and a full copy on disk each time. Ten worktrees of a large JavaScript app can take more space than the repo's whole history. A package manager with a shared store (pnpm, for example) makes this much cheaper. Symlinking node_modules from the main checkout looks clever and breaks the first time a branch changes a dependency.
Ports collide. Two agents that both start the dev server on port 3000 will fight: one fails to bind, or worse, one runs its browser tests against the other's server and reports results for the wrong code. Give each worktree its own port in its own .env, and tell the agent to read it:
echo "PORT=3101" >> ../app-fix-login/.envThe same goes for anything else with a fixed address: a local database name, a Docker Compose project name, a simulator.
One branch, one worktree. Git refuses to check out a branch that is already checked out elsewhere:
$ git worktree add ../app-dup agent/fix-login
fatal: 'agent/fix-login' is already used by worktree at '/Users/me/code/app-fix-login'This protects you. To look at a branch an agent is working on, use git worktree add --detach ../app-look agent/fix-login, which checks out the commit without the branch.
Submodules. The git manual says support for submodules in multiple checkouts is incomplete and recommends against making multiple checkouts of a superproject. A worktree that contains submodules also cannot be moved with git worktree move and needs --force to remove. If your repo uses submodules, test the whole cycle once by hand before handing it to an agent.
How do you clean up?
git worktree remove only deletes a clean worktree. If there are modified or untracked files it stops:
$ git worktree remove ../app-fix-login
fatal: '../app-fix-login' contains modified or untracked files, use --force to delete itRead that as a question: did the agent leave work uncommitted? Look before you add --force.
Removing a worktree never deletes its branch. Afterwards, git branch -d agent/fix-login deletes the branch if it is merged and refuses if it is not, which is the behaviour you want. If you deleted a worktree folder with rm -rf, git still lists it, marked prunable, until you run git worktree prune.
A weekly sweep keeps things honest:
git worktree list
git branch --merged main | grep 'agent/' # safe to delete
git branch --no-merged main | grep 'agent/' # work nobody has reviewed yetThe second list is the one to watch. A growing pile of unmerged agent branches means you are starting more work than you are reviewing, which is the subject of How to manage multiple Claude Code and Codex sessions.
Where Vakr fits
Worktrees are free and built into git, and Claude Code and Codex both create them for you, so nobody should pay for that. Vakr, the Mac app I make, gives every run its own branch and worktree as a matter of course, never touches main, and lists the worktrees that ended runs left behind so you can remove the clean ones. Its actual job is the step after the worktree: checking the agent's work so you can merge it without reading every line. It is in early access with a waitlist.
Questions
Do git worktrees use more disk space than a second clone?
Less for the repo itself, because all worktrees share one object store. Untracked things such as node_modules and build output are still duplicated per worktree, and those are usually the larger part.
Can two worktrees have the same branch checked out?
No. Git refuses unless you force it. Use --detach to look at the same commit in a second worktree without checking out the branch.
Is git stash shared between worktrees?
Yes. A stash made in one worktree shows up in git stash list in all of them. With several agents in one repo, have them commit to their own branch and leave the stash alone.
Does removing a worktree delete the branch?
No. git worktree remove deletes the folder and git's record of it. Delete the branch separately with git branch -d, which refuses if the branch has not been merged.
Why is my .env file missing in the new worktree?
Because it is gitignored, and a worktree is a checkout of tracked files only. Copy it in when you create the worktree, or use a .worktreeinclude file if Claude Code creates the worktrees.
How Vakr compares with other tools for running agents: One, Orca, T3 Code, Agentbox and Conductor.