Git worktrees for AI agent workflows

If you use AI coding agents seriously, Git worktrees stop feeling like an advanced Git feature and start feeling like basic infrastructure.

They solve a very specific problem: you want multiple isolated working directories for the same repository, at the same time, without cloning the repo again and again.

That becomes especially useful when:

  • one agent is building a feature
  • another agent is fixing a bug
  • you need to review a branch without disturbing your current work
  • a long-running test or build should run on a frozen snapshot while you keep coding

For AI-assisted development, that isolation matters a lot. Agents are not good at sharing one messy working tree. Worktrees give each session its own clean filesystem.

Mental model first

The easiest way to understand worktrees is this:

  • one repository has one .git database
  • that database can back multiple working directories

So instead of:

  • one repo
  • one branch checked out
  • one folder

you get:

  • one repo history
  • multiple checked-out branches
  • multiple folders on disk
my-app/                 ← main worktree
  .git/                 ← the real git database
  apps/ packages/ ...

my-app-feature-a/       ← extra worktree
  .git                  ← pointer back to the shared git database
  apps/ packages/ ...

my-app-hotfix/          ← another worktree
  .git                  ← same shared history, different files checked out
  apps/ packages/ ...

The extra worktree is not a full clone. It only has another checked-out copy of the files. Git history and objects are shared.

That means worktrees are much cheaper than cloning the whole repository again, but still give you real isolation for the files you edit.

Why worktrees matter more with AI agents

Traditional Git workflows assume one human is switching branches in one shell.

AI workflows break that assumption.

If two agents operate in the same working directory, they can easily:

  • overwrite each other's files
  • confuse each other's build state
  • collide on generated output
  • leave you with a half-edited tree that is hard to reason about

Worktrees eliminate that entire class of problems.

Each agent gets:

  • its own directory
  • its own branch
  • its own dependency install
  • its own test and dev server processes

In practice, that means you stop telling agents "be careful not to touch these files" and instead give them a workspace where there is nothing to interfere with.

That is a much better operating model.

The four commands worth memorizing

Most of daily worktree usage comes down to four commands.

Create a worktree on a new branch

git worktree add ../repo-feature-a -b feature/a main

This creates a new folder and checks out a new branch from main.

Create a worktree on an existing branch

git worktree add ../repo-review feature/some-branch

Useful for reviewing a branch or resuming existing work in a second directory.

List worktrees

git worktree list

This shows every active worktree and which branch is checked out in each.

Remove a worktree when you are done

git worktree remove ../repo-feature-a

That is the basic lifecycle.

Real scenarios where worktrees shine

1. Parallel agents, same repository

You are already working on one branch, and you want a second agent to tackle a different task without touching your current filesystem.

git worktree add ../repo-sharing -b feature/sharing main
cd ../repo-sharing
cp ../repo/.env .env
pnpm install

Now one agent can keep working in the original folder while another works in the sibling worktree.

This is the most important worktree use case for AI development.

2. A hotfix interrupts a messy feature branch

You are deep in a refactor. Files are half-done. Tests are broken. Then a production bug shows up.

Without worktrees, the common pattern is:

  • stash everything
  • switch branches
  • make the fix
  • switch back
  • restore the stash
  • hope nothing conflicts

With worktrees:

git worktree add ../repo-hotfix -b hotfix/login-crash main
cd ../repo-hotfix

Your hotfix happens in a clean directory, and your messy feature branch remains untouched.

3. Long-running tests on a frozen snapshot

Sometimes you want to run a heavy test suite while continuing development.

git worktree add ../repo-test HEAD
cd ../repo-test
pnpm test:integration

That test run now executes against a stable snapshot. Your active edits in the main worktree do not change what the test process sees.

4. Reviewing another branch locally

git worktree add ../repo-review origin/feature/pr-branch
cd ../repo-review
pnpm install
pnpm dev

This is cleaner than switching your current checkout back and forth. Your editor state, shell history, and in-progress files all stay where they were.

5. Comparing two approaches side by side

If you want to spike two implementations and compare them properly:

git worktree add ../repo-redis -b spike/cache-redis main
git worktree add ../repo-lru -b spike/cache-lru main

Open both directories side by side, benchmark them, and keep the one that wins.

A practical workflow for AI-assisted development

The simplest reliable pattern is:

one worktree per issue or task

That means each meaningful unit of work gets:

  • one directory
  • one branch
  • one agent session

Example:

git fetch origin
git worktree add ~/code/repo-wt/issue-auth-cleanup -b issue/auth-cleanup origin/main
cd ~/code/repo-wt/issue-auth-cleanup
cp ~/code/repo/.env .env
pnpm install

Now that directory belongs to exactly one task.

You can do the same for:

  • a feature implementation
  • a bug fix
  • a refactor
  • a review session
  • a performance investigation

This is especially useful if you run multiple AI agents in parallel. Each session has a clear scope and a clear filesystem boundary.

A folder structure that scales

One clean pattern is:

~/code/repo/               ← main checkout
~/code/repo-wt/
  feature-auth/
  bug-search-crash/
  spike-cache-layer/
  review-pr-128/

Keeping worktrees in a sibling -wt directory avoids clutter and makes it obvious which folders are temporary working environments.

A small shell helper

If you use worktrees often, a shell function saves time.

# Usage: repowt feature-auth
repowt() {
  local name=$1
  local root="$HOME/code/repo"
  local dir="$HOME/code/repo-wt/$name"

  git -C "$root" worktree add "$dir" -b "$name" origin/main
  cp "$root/.env" "$dir/.env" 2>/dev/null
  cd "$dir" && pnpm install
}

Then creating an isolated worktree becomes a one-command setup step.

Gotchas you will run into

Dependency installs are still per worktree

Each worktree has its own checked-out files, so you usually still run pnpm install in each one.

The good news is that package managers like pnpm already deduplicate heavily through a global store, so the cost is often smaller than it first looks.

Environment files are not copied automatically

If .env files are gitignored, a new worktree will not have them. Copy them explicitly or script that setup.

Port collisions are common

If you run multiple dev servers from multiple worktrees, they may all try to bind the same ports. Either:

  • run only one dev server at a time
  • or override ports through env vars

You cannot check out the same branch twice

This is a Git safety feature. A branch can only be checked out in one worktree at a time.

That is not something to work around. It is exactly what prevents corruption.

Deleting a worktree folder manually leaves stale state

If you remove a worktree with rm -rf instead of git worktree remove, Git still remembers it.

When that happens:

git worktree prune

Incremental caches can get weird

Sometimes .turbo, tsconfig.tsbuildinfo, or other build caches go stale per worktree. Usually deleting them fixes the issue quickly.

When not to use worktrees

Worktrees are excellent, but not every branch switch needs one.

Skip them when:

  • you only need a quick 30-second checkout
  • you are doing single-threaded work in one branch
  • your machine is very disk-constrained

They are a tool for parallelism and isolation. If you do not need either, plain git switch is simpler.

The short version

A Git worktree is an additional checkout of the same repository, on its own branch, sharing history but keeping its files isolated from your other working directories.

That makes it ideal for AI-assisted development.

If you are running multiple agents, juggling hotfixes, reviewing code locally, or testing alternative implementations in parallel, worktrees turn a messy branch-switching workflow into something much calmer and more reliable.

The core command is simple:

git worktree add <path> -b <branch> main

If your development style is starting to look more like orchestration than single-threaded coding, worktrees are one of the highest-leverage Git habits you can adopt.