Guides

Git worktrees for AI coding agents

Coding agents edit files, run tests and make commits on their own. Give two of them the same folder and they get in each other's way. Git has had a built-in answer since version 2.5: worktrees. This guide explains what a worktree is, the handful of commands you need, the details that catch people out, and how Yami uses worktrees for its agents.

What a worktree is

Every git repository has a main working tree: the folder with your files, where .git lives. git worktree lets you attach more working trees to the same repository, each in its own folder. A linked worktree has its own files, its own staging area and its own checked out branch, but it shares everything else with the main one: the commits, the branches, the tags, the remotes and the config.

Compared with a second clone, a worktree costs only the checked out files, not another copy of the history. A commit made in one worktree is visible from all the others at once, with no push or fetch in between. That is what makes worktrees a good fit for agents: each gets a separate desk, but they all work in one repository.

The commands you need

Create a worktree with a new branch, starting from main:

git worktree add -b agent/api ../myapp-api main

Check out a branch that already exists:

git worktree add ../myapp-fix fix/typo

Make a throwaway worktree with no branch at all (a detached HEAD), for a quick experiment:

git worktree add --detach ../myapp-try HEAD

See every worktree, with its folder, commit and branch. Scripts should use the --porcelain form, which is stable to parse:

git worktree list
git worktree list --porcelain

Remove a worktree when you are done. Git refuses if it has uncommitted or untracked files; --force removes it anyway and discards them:

git worktree remove ../myapp-api
git worktree remove --force ../myapp-api

If a worktree folder was deleted by hand, git still has a record of it. prune clears those records:

git worktree prune

Two more are handy now and then. git worktree move moves a worktree to a new folder, and git worktree lock keeps a worktree from being pruned, for example while it sits on a drive that is not always connected:

git worktree move ../myapp-try ../myapp-experiment
git worktree lock --reason "on an external drive" ../myapp-fix

Why agents need separate checkouts

A person working in a folder knows what they changed. An agent assumes the files on disk are the result of its own edits. When two agents share a folder, that assumption breaks in several ways:

• Edits cross. One agent rewrites a file while the other is halfway through changing it, and one set of changes is lost or mangled.
• Tests lie. A test run picks up the other agent's half finished work and fails for reasons the agent cannot see, so it starts "fixing" code that was not broken.
• Commits mix. git add -A stages everything in the folder, including the other agent's files.
• Branches move under them. If one agent runs git switch, every file in the folder changes for the other one too.

With one worktree per agent, each agent's view of the files is its own, and its branch records exactly what it did. You can review each branch on its own and merge them one at a time. The guide on running several Claude Code agents in parallel walks through that whole flow.

Details that catch people out

• One branch, one worktree. Git will not check out a branch that is already checked out in another worktree; it stops with an error that says the branch "is already used by worktree". Give every agent its own branch.
• Only tracked files come along. A new worktree has no .env, no node_modules and no build output. Copy the files you need and install dependencies in each worktree before an agent runs anything.
• Shared ports and databases. Two dev servers on the same port, or two test runs against the same local database, still collide. Give each worktree its own port or test database.
• Hooks and config are shared. The repository's git hooks and settings apply in every worktree, so a slow pre-commit hook runs for every agent's commit.
• Where to put them. A sibling folder such as ../myapp-api, or a separate folder outside the project, keeps the worktree out of your editor's search and out of the main checkout's file list. If you keep them inside the project, add that folder to .gitignore.

A small script for several agents

To set up one worktree per task in one go:

for task in login search settings; do
  git worktree add -b "agent/$task" "../myapp-$task" main
done

Then open a terminal in each folder and start an agent there. Each one commits to its own agent/... branch.

Cleaning up

Worktrees are cheap, but they pile up. After a branch is merged, remove its worktree and delete the branch:

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

To see which agent branches are already merged, list them against main. A + in front of a name means that branch is still checked out in a worktree:

git branch --merged main --list 'agent/*'

git branch -d refuses to delete a branch that is not merged, which keeps unreviewed work safe; -D deletes it anyway. Finish with git worktree prune and git worktree list to check that only the worktrees you still use are left.

How Yami automates it

Yami is a free desktop app for macOS (Apple silicon) and Windows 11. In a venture, a leader agent writes a plan and up to eight agents work on its tasks at once (four by default, set in Settings). Yami does the worktree work for them:

• Each agent gets its own worktree under ~/Yami/Worktrees, in a folder for the venture, on its own branch.
• When the leader says a branch is good, Yami merges it into the branch you are on. Before merging it checks that the branch is one of Yami's own, that the worktree is in Yami's worktree folder, and that it belongs to the same repository. Your repository's git hooks are turned off for these merges.
• Your approval mode decides whether starting an agent and merging its branch ask you first. In Bypass nothing asks, and each merge is logged and shown with an Undo merge button.
• A folder without git gets one agent at a time, since there is nothing to keep the agents apart.