What is a git worktree?
A git worktree is an extra working directory attached to the same repository. Each worktree has its own files and its own checked-out branch, but every worktree shares one .git history, one set of remotes and one object store. A commit made in any worktree is immediately visible from all the others.
You get the effect of cloning your repository several times, without the extra clones: creating a worktree takes seconds, copies only the checked-out files and needs no second git fetch.
| Branch switching | Second clone | Worktree | |
|---|---|---|---|
| Separate files on disk | No | Yes | Yes |
| Shared history and remotes | Yes | No, fetched separately | Yes |
| Several branches open at once | No | Yes | Yes |
| Setup time | Instant | A full clone | Seconds |
Why AI coding agents need worktrees
One agent in one folder is fine. Two agents in the same folder share every file. While one agent is halfway through a refactor, the other can reformat the same file, install a dependency, or run tests against code that is half-edited. Neither agent knows the other is there.
A worktree gives each agent its own copy of the files and its own branch. Agents work side by side, each commit stays on its own branch, and you combine the results when you merge, one branch at a time.
How to use git worktrees: the five commands
These work with any agent or editor, and are all you need for a manual setup.
Create a worktree on a new branch:
git worktree add ../myapp-invoices -b invoices-api
This creates the folder ../myapp-invoices with the branch invoices-api checked out, starting from your current commit. Add a start point to branch from somewhere else, for example git worktree add ../myapp-invoices -b invoices-api main.
Create a worktree for a branch that already exists:
git worktree add ../myapp-bugfix fix-login-redirect
List every worktree:
git worktree list
Remove a worktree when you're done:
git worktree remove ../myapp-invoices
Git refuses if the worktree has uncommitted changes. Commit or discard them first, or add --force once you're sure.
Tidy up after folders deleted by hand:
git worktree prune
One rule to know: a branch can be checked out in only one worktree at a time. If git worktree add says a branch is already checked out, create a new branch for the new worktree instead.
Claude Code worktrees: step by step
Claude Code creates and cleans up worktrees for you.
1. Start a session in a new worktree. From your repository root:
claude --worktree invoices-api
Claude Code creates .claude/worktrees/invoices-api/ on a new branch called worktree-invoices-api and starts the session there. Run the command again in another terminal with a different name to start a second agent. -w is the short form, and leaving out the name generates one.
2. Keep worktrees out of git status. Add the folder to .gitignore once:
echo ".claude/worktrees/" >> .gitignore
3. Copy your local config into every worktree. A new worktree has tracked files only, so .env and other gitignored files are missing. List them in a .worktreeinclude file at the repository root, in .gitignore syntax:
.env
.env.local
Claude Code copies every matching gitignored file into each worktree it creates.
4. Choose the starting point. By default, new worktrees branch from your repository's default branch on the remote, usually main. To branch from your current local work instead, set this in .claude/settings.json:
{
"worktree": { "baseRef": "head" }
}
To start from a pull request, pass its number: claude --worktree "#1234".
5. Let Claude Code clean up. When you exit, Claude Code removes a clean worktree from an unnamed session along with its branch. If the worktree has changes or new commits, it asks whether to keep or remove it. Kept worktrees can be resumed with claude --worktree <name> --resume, the command Claude Code prints on exit.
Background sessions started with claude --bg "<task>" move into their own worktree automatically before they edit files, and subagents with isolation: worktree in their frontmatter get one each. Both are covered in How to run multiple Claude Code agents in parallel.
Codex worktrees: step by step
Codex runs in whatever directory you start it in, so you create the worktrees with git and start one Codex session in each:
git worktree add ../myapp-search -b search-filters
git worktree add ../myapp-emails -b email-templates
cd ../myapp-search && codex
# in a second terminal
cd ../myapp-emails && codex
For a hands-off run, use codex exec with the task as the prompt, one per worktree:
(cd ../myapp-search && codex exec "add date filters to the search page, with tests") &
(cd ../myapp-emails && codex exec "move the email templates to the new layout") &
wait
The same pattern works for Claude Code, Gemini CLI or any other terminal agent, and for a mix: Claude Code in one worktree, Codex in the next.
Set each worktree up to run
A worktree shares history, not the build environment. For each one:
- Install dependencies.
node_modules, virtual environments and build output live in the working directory. Run your setup command in each worktree, or ask the agent to as its first step. - Use different ports. Two dev servers can't both use port 3000. Give each agent a port in its task.
- Separate local databases. Agents running migrations against one shared database can clash. Give each worktree its own database name, or keep migrations to one task.
- Check disk space. Each worktree is one copy of your checked-out files plus whatever the setup installs. The git history is not copied.
Merge the results
Each agent finishes on its own branch. Review and merge them one at a time:
git log --oneline main..invoices-api
git diff main...invoices-api
git switch main && git merge invoices-api
Run your tests after each merge. Merging branch by branch keeps any conflict small and easy to place, and if a later branch needs updating, rebase it on the new main from inside its own worktree.
Cleaning up worktrees
git worktree list
git worktree remove ../myapp-invoices
git branch -d invoices-api
git worktree prune
git branch -d deletes a branch only after it's merged, which makes it a safe last step. If git refuses to remove a worktree because it is locked, run git worktree unlock <path> first.
How Chief keeps parallel agents apart
Worktrees solve isolation at checkout time. Chief works one step earlier, at planning time, so you don't have to create, track or clean up a worktree per agent.
- Chief plans which work can run together. You set a goal, and Chief breaks it into milestones, each with a definition of done and the milestones it depends on. Work that would mostly edit the same files is chained or merged into one milestone, and shared pieces such as types, interfaces and migrations come first.
- Independent milestones run in parallel. Chief runs every milestone whose dependencies are done at the same time, through the Chief relay on your computer, in your project folder, with your own Claude Code, Codex and other agent subscriptions.
- Every change is traceable. Each agent commits only the files it changed for its task, with the task in the commit message, so you can see which milestone produced each change.
- Every result is reviewed. Chief checks each finished milestone against its definition of done and collects the decisions only you can make in one queue.
When you work by hand alongside Chief, a worktree is a good home for your own session: your edits stay on your branch while Chief's agents work in the project folder.
See Chief and Codex and Chief and Claude Code for how Chief works with each, or the multi-agent orchestration guide for the wider picture.
FAQ
What is the difference between git worktree and git clone?
A clone is a separate repository with its own history, remotes and objects, fetched over the network. A worktree is another working directory of the same repository: it shares history and remotes, takes seconds to create and needs no fetch. Commits in one worktree are instantly visible in all the others.
Where should I put git worktrees?
Anywhere outside your main checkout's tracked files. A sibling folder such as ../myapp-feature keeps them apart. Claude Code puts its worktrees in .claude/worktrees/ inside the repository, so add that folder to .gitignore.
Do worktrees copy my .env file?
No. A new worktree contains tracked files only. Copy gitignored files yourself, or list them in a .worktreeinclude file and Claude Code copies them into every worktree it creates.
Can two worktrees use the same branch?
No. Git lets a branch be checked out in only one worktree at a time. Create a new branch for each worktree, which is what you want for parallel agents anyway.
Does Chief use git worktrees?
No. Chief runs agents in your project folder and keeps parallel milestones apart when it plans them: work that would edit the same files is chained or combined, and independent work runs at the same time. You can still use worktrees for your own sessions next to Chief.