Git Worktrees: Why AI Agents Need Them

Most developers know branches. Fewer know about git worktrees — a built-in feature that lets you have multiple branches checked out at the same time, each in its own directory, sharing a single repository.

If you’ve ever stashed work to jump on a hotfix, cloned a repo twice to compare branches, or tried running multiple AI agents on the same codebase — worktrees solve all of that.

The Problem Worktrees Solve

Git normally gives you one working directory. One branch checked out at a time. Want to look at another branch? You git stash, git checkout, do your thing, then switch back and git stash pop. It works, but it’s tedious and error-prone.

Another option is a separate clone. Its storage and setup cost depend on clone options and repository size. Worktrees reuse the existing repository’s objects, though checked-out files, dependencies, and build output still take space in each directory.

Worktrees give you the best of both worlds: multiple checked-out branches with minimal git overhead.

How Worktrees Work

A linked worktree is an additional working directory attached to your existing repository. It normally checks out its own branch; a detached worktree can instead check out a commit without a branch. Each has its own files, HEAD, and index, while sharing repository objects and most refs.

# Create a worktree with a new branch
git worktree add -b feature/auth ../my-repo-auth main

# Create one from an existing branch
git worktree add ../my-repo-staging staging

These examples assume local main and staging branches exist, staging is not checked out elsewhere, and the new path and branch name are unused. Replace them with your actual branch names. Choose a committed starting point: omitting the final base in the first command uses the current HEAD, and uncommitted edits are not copied into the new worktree.

If you let Claude Code create the worktree, use the Claude Code worktree base guide to choose and verify its starting commit.

After running the first command, you have two directories:

my-repo/              ← your original working tree (e.g. on main)
my-repo-auth/         ← new worktree on feature/auth

Both are working copies where you can build and commit. Ordinary file edits and staging are separate, but branches, remotes, and repository configuration are generally shared. Ports, databases, and symlinked directories can still collide. For concurrent coding sessions, the multiple-agent workflow guide covers task boundaries and the resources you must separate beyond Git.

Everyday Use Cases

Hotfix while mid-feature. You’re deep into a feature branch when a production bug comes in. Instead of stashing and switching, create a worktree from main, fix the bug, push, and delete the worktree. Your feature branch stays untouched.

git worktree add -b hotfix/login-crash ../hotfix main
cd ../hotfix
# fix, commit, push
cd -
git worktree remove ../hotfix

Comparing branches side by side. Need to look at how two branches implement the same thing? Check both out as worktrees and open them in separate editor windows.

Running CI locally on multiple branches. Test your feature branch and main simultaneously without waiting for one to finish before starting the other.

Parallel AI agents. Give each independent editing task a separate directory and branch. Worktrees separate working copies, but they are not a security sandbox and do not prevent later merge conflicts. The agent isolation guide explains that boundary.

The Full Lifecycle

# Create
git worktree add -b my-branch ../my-worktree

# List all worktrees
git worktree list

# Remove when done (clean working tree required)
git worktree remove ../my-worktree

# Preview stale records for worktree directories that are already gone
git worktree prune --dry-run
# Prune only after confirming those directories were intentionally removed
git worktree prune

Removal keeps the branch and its commits. Inspect local changes, ignored files, and branch-only commits before cleanup; a clean status alone does not mean all work has been integrated. Follow the safe worktree cleanup procedure before deleting branches or forcing removal.

Gotchas to Know About

A branch is normally checked out in one worktree at a time. If creation fails, use git worktree list to find its current location. The branch already checked out troubleshooting guide explains when to reuse that directory, create another branch, or inspect a detached worktree. Do not bypass the guard with --force just to silence the error.

Submodules need extra attention. Git documents incomplete multiple-checkout support for superprojects with submodules. Check the worktree manual’s limitations for your Git version and verify your submodule workflow before relying on parallel checkouts; initialization alone is not a guarantee of support.

Don’t forget to clean up. Worktrees are cheap, but stale ones accumulate. Run git worktree list periodically and remove ones you’re done with. git worktree prune cleans up references to deleted directories.

Ignored files are not copied automatically. Install dependencies and supply the local environment files each task needs. Symlinking mutable dependencies can reintroduce shared state. Give running services separate ports and isolate test databases as well.

Check hooks in the new checkout. If a commit or push skips an expected check, follow the guide to Git hooks in agent worktrees to inspect the effective hook path and how the command was invoked.

Other branches keep moving. Creating a worktree does not keep it synchronized with later changes to main. When a task needs those commits, follow the guide to updating a worktree branch from main and rerun its checks.

Key Takeaways

Git worktrees let you check out multiple branches simultaneously from one repo
They reuse repository objects; working files and dependencies still consume space
Useful for hotfixes, branch comparison, parallel checks, and multi-agent development
Four commands: add, list, remove, prune
Built into git — no plugins or extensions needed