Git worktrees for AI coding agents: one repo, many parallel branches

The first real problem with running several AI coding agents on one project isn't the agents. It's that they're all standing in the same room. One checks out a branch, another writes a file, a third runs the test suite against a tree that changed underneath it.

git worktree fixes this properly, and it's been in Git since 2.5.

What a worktree is

A worktree is an additional working directory attached to the same repository. Same object store, same history, same remotes — but a separate directory with its own checked-out branch and its own index.

# from your main checkout
git worktree add ../myapp-auth feature/auth
git worktree add ../myapp-billing feature/billing

You now have three directories on disk, each on its own branch, sharing one .git. Point one agent at each. They cannot collide, because they aren't in the same files.

Why not just clone the repo three times?

Clones work, but they cost more and drift more:

• Disk — each clone duplicates the entire object store. Worktrees share it.
• Fetching — three clones means three git fetch runs to stay current. Fetch once in a worktree setup and every worktree sees the new objects immediately.
• Branch confusion — clones let two directories check out the same branch and diverge silently. Git refuses to check out one branch in two worktrees, which is exactly the guardrail you want when agents are choosing branches on their own.

That last point matters more than it sounds. An agent told to "work on the login fix" may check out the same branch another agent is already on. With clones, you find out at merge time. With worktrees, Git stops it at the door.

A working setup

# one-time: keep worktrees in a sibling directory
mkdir -p ~/work/myapp-trees

# per agent task
git worktree add -b feature/rate-limit ~/work/myapp-trees/rate-limit main
git worktree add -b feature/csv-export ~/work/myapp-trees/csv-export main

The -b form creates the branch and the directory in one step, based on main. Each agent gets started in its own directory and never needs to run git checkout at all — which removes the single most common way agents disturb each other.

When a task is done and merged:

git worktree remove ~/work/myapp-trees/rate-limit
git branch -d feature/rate-limit

If you forget the remove and delete the folder by hand, git worktree prune cleans up the stale references.

The parts that bite

Untracked files don't come along. .env, local config, and anything gitignored exist only where you created them. A fresh worktree will be missing them, and your agent's first test run will fail for a reason that has nothing to do with its task. Symlink or copy them as part of your setup step.

Dependencies are per-directory. node_modules, .venv, target/ — each worktree needs its own install. This is real time and real disk. Package managers with a global content-addressed store (pnpm, uv) make it much cheaper. Budget for the install, or use a shared store.

Hooks and local Git config are shared. They live in the common .git, so a hook you add applies everywhere. Usually convenient, occasionally surprising.

Submodules need initializing in each new worktree.

A small setup-worktree.sh that creates the tree, links the env files, and installs dependencies turns all four of these into one command — worth writing on day one.

Pairing it with a fleet

Worktrees solve isolation on disk. They don't solve knowing which agent is where. Once you have five directories and five sessions, the questions become: which tile is csv-export, which one is waiting on you, and can you tell all five to git pull --rebase origin main without typing it five times?

That's the layer above worktrees: sessions that are labeled by project, grouped so one instruction reaches several at once, and restorable in their own folder after a restart. Worktrees make parallel work safe. Session management makes it legible.

The short version

One repo, one object store, many directories, one branch each, no collisions. It costs you a setup script and some disk, and it removes an entire category of "why did my tests just break" from parallel agent work.