Parallel Agents with Git Worktrees

Most developers have never used git worktrees. The feature has been in git for years but sits in a corner of the docs nobody visits. Then agentic coding IDEs showed up and worktrees turned out to be the single most important primitive in the whole toolchain for making parallel agents actually useful. Once the pattern is visible it is obvious — but almost nobody teaches it, and almost nobody uses it.

This lesson fixes that. By the end, you will be spawning three or four agents in parallel on the same repo, each working on a different feature branch, each in its own isolated working directory, with zero conflicts and zero ceremony.

The Problem Worktrees Solve

You have a repo. You want to try three different approaches to a refactor in parallel, or fix three different bugs at the same time, or let one agent run a long migration while you keep working on features. The naive approach is to clone the repo three times, but that wastes disk space, loses git history sharing, and means each clone has its own stale copy of the same branches.

The second naive approach is to git checkout between branches as you work. This serializes everything — you cannot have branch A and branch B both in a usable state simultaneously because your working directory can only be on one branch at a time.

Git worktrees fix this. A worktree is a second working directory pointing at the same repository. Same .git metadata, same commit history, different physical directory on disk, different HEAD, different staging area. You can have as many as you want.

The Four Commands You Actually Need

Git worktrees have more commands than this, but these four cover 99% of real use.

# 1. Create a new worktree at a new path on a new branch
git worktree add ../myproject-feat-auth feat/auth

# 2. List all active worktrees
git worktree list

# 3. Remove a worktree when done (does NOT delete the branch)
git worktree remove ../myproject-feat-auth

# 4. Prune stale worktrees that got deleted manually
git worktree prune

That is the entire API surface you need to remember. Run git worktree add ../myproject-feat-auth feat/auth from your main repo and git creates a complete working directory at that path, checks out the feat/auth branch into it, and you can cd there and work normally. The main working directory is untouched.

Running Agents in Worktrees

The interesting part — actually spawning agents in parallel worktrees. Here is the pattern that Claude Code's Agent tool uses under the hood when you pass it isolation: "worktree".

# Spawn three agents on three different features, in parallel
cd ~/code/myproject

git worktree add ../myproject-feat-auth    feat/auth
git worktree add ../myproject-feat-search  feat/search
git worktree add ../myproject-bugfix-429   bugfix/rate-limit

# Launch three Claude Code sessions in three directories
(cd ../myproject-feat-auth    && claude "implement OAuth login flow") &
(cd ../myproject-feat-search  && claude "add fuzzy search to the product page") &
(cd ../myproject-bugfix-429   && claude "fix the 429 retry loop in the webhook handler") &

wait   # Wait for all three to finish

# Now review each worktree's changes independently
(cd ../myproject-feat-auth    && git diff main)
(cd ../myproject-feat-search  && git diff main)
(cd ../myproject-bugfix-429   && git diff main)

Three agents. Three branches. Three directories. Zero collisions. When they all finish, you review each branch on its own merits, merge the winners, and delete the losers. The failed worktrees cost nothing — git worktree remove and the disk space is back.

Four Real Workflows Where This Saves You Hours

Gotchas You Will Hit

Worktrees are simple but they have four rough edges. Know them before you spawn ten of them.

• You cannot check out the same branch in two worktrees. Git refuses. One branch, one worktree. Make a new branch per worktree even if the changes are similar.
• Submodules are finicky inside worktrees. They mostly work, but if your repo uses heavy submodule trees, initialize them explicitly in each new worktree (git submodule update --init).
• Hooks live in the main repo's .git/hooks. Every worktree shares the same hooks. If your pre-commit hook has side effects that depend on the worktree path, test it.
• Stale worktrees need pruning. If you delete a worktree directory with rm -rf instead of git worktree remove, git thinks it still exists. Run git worktree prune periodically to clean up phantoms.

Hands-On: Run Three Agents in Parallel

This is the most fun hands-on of the week. Pick a real project you have on disk.

1. cd into the project's root (the one with .git).
2. Create three worktrees for three feature branches you don't actually care about: git worktree add ../$(basename $PWD)-exp-1 exp/1, same for 2 and 3.
3. Open three terminal windows. In each, cd into one of the new worktree directories.
4. In terminal 1, touch a file: echo "// exp 1" >> README.md && git commit -am "exp 1".
5. In terminal 2, touch a different file: echo "// exp 2" >> README.md && git commit -am "exp 2".
6. In terminal 3, do the same with a third message.
7. Run git worktree list from any terminal. You should see all four worktrees (main + three exps) with their commit hashes and branches.
8. Clean up: git worktree remove ../$(basename $PWD)-exp-1 and same for 2 and 3. Then git branch -D exp/1 exp/2 exp/3 to delete the branches.

You just ran three parallel branches through three independent working directories on one repo. That is the whole pattern. Now replace those touching README with three agents working on three real features and you are running parallel agentic development. It's identical.

What's Next

You can now spawn agents in parallel. Day 4 handles the harder half of the problem: making sure they stop. Runaway agents that spin forever in an infinite loop are one of the most common failure modes in production — tomorrow we learn the four stopping conditions every serious agentic IDE uses.