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.

The alternative — cloning the repo again — is worse. A remote clone duplicates the entire .git object database, and you need a separate npm install (or equivalent) for each copy. On a large monorepo, that’s gigabytes of disk and minutes of setup.

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

How Worktrees Work

A worktree is an additional working directory linked to your existing repository. It gets its own branch and file tree, but shares the same .git object store.

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

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

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 fully functional. You can cd into either, run builds, make commits — completely independently. But under the hood, they share the same git history, remotes, and object storage.

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
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. Each coding agent needs its own directory and branch to avoid stepping on each other’s files. Worktrees provide exactly that — isolated working directories with zero duplication.

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

# Clean up stale references
git worktree prune

That’s it. Four commands cover 99% of worktree usage.

Gotchas to Know About

One branch per worktree. This prevents conflicting writes to the same branch. You can override with --force, but in practice each worktree should have its own branch.

Submodules need extra attention. Submodules are initialized per-worktree. If your project uses them, you’ll need to run git submodule update --init in each new worktree.

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.

Shared gitignored files (like node_modules) aren’t shared. Each worktree has its own working directory, so you’ll need a separate npm install per worktree. Some tools work around this with symlinks.

Key Takeaways

Git worktrees let you check out multiple branches simultaneously from one repo
They share the .git object store, so creation is near-instant and git overhead is minimal
Perfect for hotfixes, branch comparison, parallel CI, and multi-agent development
Four commands: add, list, remove, prune
Built into git — no plugins or extensions needed