Git worktrees for AI coding agents: a practical guide

If you run more than one coding agent on a repository, give each its own checkout. Git has had the tool for this since 2015: git worktree. This guide covers the commands, the things that trip people up, and how to clean up without losing work.

What a worktree is

A worktree is an extra working directory attached to the same repository. All worktrees share one object database, so creating one is fast and costs only the size of the checked out files. Each worktree has its own branch, index and working files, so an agent in one can't touch the files of an agent in another.

Compared with cloning the repository again, worktrees share history and remotes, and a commit made in one is immediately visible to the others: no pushing between clones.

The commands you need

# New worktree on a new branch, next to the main checkout
git worktree add -b agent/search ../shop-search

# New worktree on an existing branch
git worktree add ../shop-review feature/review

# See them all
git worktree list

# Remove one (refuses if it has uncommitted changes)
git worktree remove ../shop-search

# Forget worktrees whose directories you deleted by hand
git worktree prune

Then start the agent inside it: cd ../shop-search && claude. When it is done, review and merge its branch like any other.

Pitfalls

One branch, one worktree

Git won't check out the same branch in two worktrees. That is a feature: give each agent its own branch (agent/<task> is a good convention) and merge afterwards.

Untracked files don't come along

A new worktree contains only tracked files. Your .env, local config and other ignored files stay in the main checkout. Copy what the agent needs, or keep a script that sets a worktree up.

Dependencies are per worktree

node_modules, Python virtual environments and build directories are ignored files too, so each worktree needs its own install. Package managers with a shared store (pnpm, uv, Cargo's registry cache) keep this fast; plan for the first build to take a while.

Ports and databases collide

Two dev servers from two worktrees both want port 3000, and both may point at the same local database. Give each worktree its own port, and be careful with migrations.

Removing a worktree can lose work

git worktree remove refuses when there are uncommitted changes, unless you add --force. Deleting the directory with rm -rf skips that check entirely. Commit or stash first, and never force-remove an agent's worktree you haven't looked at.

Where to put them

Siblings of the main checkout (../shop-search) are easy to find. A dedicated folder keeps your projects directory tidy. Avoid putting worktrees inside the main checkout: tools that scan the repository will find a second copy of everything.

Worktrees in Hive

Hive does the bookkeeping. Ctrl+Space C opens a terminal in a new worktree on a fresh branch named hive/shell-<id>; start any agent there. From the command line:

hive new codex -w             # new worktree, branch hive/codex-<id>
hive new claude -b login-fix  # new worktree on branch login-fix
hive worktree list
hive worktree rm <path>

Worktrees live under ~/.local/share/hive/worktrees by default (set [worktrees] dir to change it). The sidebar marks worktree agents with their branch, and Hive warns when two agents share a directory. It never removes a worktree with uncommitted changes or one still in use without being forced, and it never deletes branches: your agent's work stays until you decide.

For the bigger picture of running agents in parallel, see how to run several AI coding agents at once.