Updated 8 October 2026

Git worktrees for AI coding agents

Give each agent its own git worktree: a second checkout of your repository, in its own folder, on its own branch. Two agents can then edit the same project at once without overwriting each other, because they never share a file on disk. A worktree is a fresh checkout, though, so it starts without your installed dependencies and without untracked files such as .env, and it stays on disk until you remove it.

This page covers the commands, then the three parts that bite. For running several agents end to end, see how to run coding agents in parallel. Disclosure: Agency, the app mentioned below, is ours, and this site is its home.

How do you use git worktrees with Claude Code or Codex?

Make the worktree, then start the agent inside it. The agent sees an ordinary folder, so any agent CLI works. These commands run from inside a repository called myapp:

git worktree add -b agent/fix-login ../myapp-fix-login main
cd ../myapp-fix-login
claude

The first line creates the folder ../myapp-fix-login and a new branch agent/fix-login cut from main. Start Codex, Gemini CLI or any other agent in the same way. Claude Code can also make the worktree itself: claude --worktree fix-login creates one under .claude/worktrees/fix-login (its documentation).

Two commands help you keep track:

git worktree list
git worktree prune

list shows every worktree with its folder and branch. prune forgets worktrees whose folders you deleted by hand.

What a worktree shares and what it does not

All worktrees of a repository share one history, so a commit made in one is visible from the others, and they share the same objects, so a second worktree does not copy the repository. Git also refuses to check out one branch in two worktrees at once, which is what keeps two agents from committing onto the same branch.

Each worktree has its own working files, and that is the part that surprises people. Git materializes only the files it tracks. Anything ignored or untracked stays behind in the original folder.

Dependencies are per worktree

node_modules, virtual environments and build output are not tracked, so a new worktree has none of them. An agent that starts there runs its tests, finds nothing installed, and either fails or starts installing on its own. Install before the agent starts:

cd ../myapp-fix-login
pnpm install

The cost is real on a large project: every worktree holds its own installed copy, so disk use grows with the number of agents. A package manager that keeps one shared store and links from it makes the installs quick and small. Build output and dev servers are per worktree as well, so two worktrees that both start a server on port 3000 collide. Give each one its own port.

Untracked files like .env are not copied

A .env file is usually ignored by git for good reason, which means git worktree add leaves it out. The agent then starts without its credentials or local settings and fails in ways that look like bugs in your code. Copy what the project needs into each worktree:

cp .env ../myapp-fix-login/.env

Copy, do not link, if the agent might edit the file. A later change to the original does not reach a worktree that already has its own copy. And think before you copy a secret into a folder an agent runs in: the agent can read everything in it.

Clean up when you are done

A finished worktree costs a full checkout, and its branch stays in the repository until you delete it. Merge what you want to keep, then remove both:

git merge agent/fix-login
git worktree remove ../myapp-fix-login
git branch -d agent/fix-login

git worktree remove refuses to run when the worktree has uncommitted changes or untracked files; add --force only after you have looked at what would be lost. git branch -d refuses to delete a branch that is not merged, which is the check you want: -D deletes the branch and its unmerged commits stay reachable only through the reflog for a while.

Abandoned runs are the usual leak. Run git worktree list now and then, and remove the ones you no longer need.

Keep the worktrees out of your diffs

If you create worktrees inside the repository, which is convenient, git reports them as untracked content in the main checkout, and they turn up in every git status. Either create them next to the repository, as above, or add the folder to .git/info/exclude, which is your own ignore list and is not committed.

What Agency does for each of these

Agency is a free, open-source desktop app for macOS and Linux that runs agent CLIs in real terminals, one worktree per run. As of October 2026 it handles the parts above like this, checked against its source.

The setup script and the copy list look like this in .agency/agency.toml:

[scripts]
setup = "pnpm install"

[files]
copy = [".env", "config/certs"]

Copying skips paths that do not exist, that are absolute, or that climb out of the project with ... Directories copy recursively. Files are copied when the worktree is created or restored, so a later edit to the project's .env does not follow.

On cleanup, Agency decides whether a branch is safe to delete by asking git, locally and without the network: the branch is merged into the base, every commit is on some remote branch, or it has no commits of its own. If the branch is none of those, archiving keeps the branch so the run can be restored. If the worktree has uncommitted changes, nothing is treated as safe and the dialog says so before you confirm. Before any of it is removed, Agency writes a record of the run (prompt, commits, how it ended) to .agency/records/ as a markdown file you can read without the app.

Who should not use it: anyone on Windows or an Intel Mac, which Agency does not support yet, and anyone running one or two agents who is happy with the commands above. They are all you need there.

Questions

Can two agents work on the same branch in two worktrees?

No. Git refuses to check out one branch in two worktrees. Give each agent its own branch and merge them afterwards.

Why does my agent say a command or package is missing in a new worktree?

Dependencies are not tracked, so the new folder has none. Install them in that worktree before the agent starts.

Do worktrees take a lot of disk space?

Not for history, which is shared. The cost is each worktree's checked-out files plus its own dependencies and build output, so it grows with project size and agent count.

Where does the agent's own history go when I delete a worktree?

That depends on the agent. Some CLIs file their conversations under the folder's path, so removing the folder strands them. If you want to resume a conversation later, keep the worktree until you are sure.