Git Worktrees for Parallel Coding Agents in 5 Minutes: Stop Serializing Your Bots

You are running a coding agent on a feature branch. It takes eight minutes. You want to kick off a second agent on a different feature while the first one runs. So you `git stash`, switch branches, run the second agent, then switch back. You unstash, half your changes are gone, and the first agent's session is broken because it lost track of which file it was editing.

This is the wrong workflow. **Git worktrees** let you check out five branches from one repo into five working directories, all sharing the same `.git` database. Every agent gets its own working tree, its own index, its own uncommitted changes. They do not see each other. They do not stomp on each other. You run them in parallel terminals and merge the winners at the end.

Five minutes to set up. Half a day of agent throughput regained.

The Mental Model

A worktree is a checked-out working directory tied to a specific branch. One repo, many worktrees:

~/code/myrepo/ ← main worktree, on `main`

~/code/myrepo/.worktrees/feat-a ← worktree on `feat/a`

~/code/myrepo/.worktrees/fix-b ← worktree on `fix/b`

~/code/myrepo/.worktrees/exp-c ← worktree on `exp/c`

All three secondary worktrees share the same `.git` directory, the same object store, the same refs. Branch updates in one worktree are visible to the others immediately. But each worktree has its own `index`, its own uncommitted edits, and its own agent process. That last point is the trick: each agent runs in its own filesystem, so file locks, build caches, and editor state never collide.

The Setup

In your repo root

mkdir -p .worktrees

Create a new branch and worktree in one command

git worktree add .worktrees/feat-a -b feat/a

git worktree add .worktrees/fix-b -b fix/b

git worktree add .worktrees/exp-c -b exp/c

List active worktrees

git worktree list

/home/you/code/myrepo 3f4a9c1 [main]

/home/you/code/myrepo/.worktrees/feat-a 8e2b7d4 [feat/a]

/home/you/code/myrepo/.worktrees/fix-b 8e2b7d4 [fix/b]

/home/you/code/myrepo/.worktrees/exp-c 8e2b7d4 [exp/c]

That is the whole install. No git plugins, no external tools, no daemon. Worktrees have been in core git since 2.5 (2015). If your `git --version` is below that, upgrade.

The Parallel-Agent Workflow

Open four terminals. In each, `cd` into a different worktree. Run your agent in each. They work in parallel, each on its own branch, none of them aware of the others.

Terminal 1

cd ~/code/myrepo/.worktrees/feat-a && claude

Terminal 2

cd ~/code/myrepo/.worktrees/fix-b && codex

Terminal 3

cd ~/code/myrepo/.worktrees/exp-c && aider --model sonnet

When an agent finishes, review the diff in that worktree, push the branch, open a PR, and clean up:

From the main worktree

cd ~/code/myrepo

git fetch .worktrees/feat-a feat/a # pull the branch ref

review, merge, push as usual

git worktree remove .worktrees/feat-a

git branch -d feat/a

git worktree prune # clean up any orphaned metadata

You can run as many worktrees as your disk and RAM will support. In practice, three to five parallel agents is the sweet spot before you start fighting for GPU tokens or hitting context-window limits on the review side.

The Gotchas

• **One branch, one worktree.** A branch can only be checked out in one worktree at a time. If `feat/a` is in `.worktrees/feat-a`, you cannot also check it out in the main worktree. Trying gives you a `fatal: 'feat/a' is already checked out at ...` error. This is the design, not a bug — it prevents the worktree-corrupting scenario where two indexes disagree about the same branch's HEAD.

• **`.worktrees/` belongs in `.gitignore`.** The worktree directory is technically inside the parent repo. Without the ignore, agents see phantom files (`feat-a/src/...`) when they run `git status` or `git diff` from the main worktree. Add this line to `.gitignore`:

.worktrees/

• **Per-worktree build caches.** Each worktree has its own `node_modules/`, `target/`, `.venv/`, `__pycache__/`. With three worktrees you triple the disk and the warm-up time. Two mitigations: symlink the cache directories across worktrees (`ln -s ../../.worktrees/feat-a/node_modules node_modules`), or run a [shared cache server](https://turborepo.com) like Turborepo, sccache, or Bazel's remote cache. For a 4-worktree day on a TypeScript repo, symlinking `node_modules` is enough.

• **Detached HEAD for one-off exploration.** If you want an agent to experiment without polluting your branch list, check out a detached commit:

git worktree add --detach .worktrees/sandbox 8e2b7d4

Throwaway branches stay out of `git branch` until you decide to keep them. Use this for "let me see what the agent does without committing to the branch name yet" sessions.

• **Editor integration matters.** VS Code's "Open Folder" per worktree is the cleanest model. JetBrains IDEs (IntelliJ, GoLand, PyCharm) detect worktrees and offer them as run configurations. Neovim with a per-worktree `:cd` is fine but loses LSP state. Pick the editor that handles multiple roots without complaining.

Verify It Works

git worktree list # should show all active worktrees

git -C .worktrees/feat-a status # should show clean tree on feat/a

git -C .worktrees/fix-b branch --show-current # should print 'fix/b'

If all three print what you expect, the setup is solid. Start your agents.

The Take

Worktrees are the only git-native way to run multiple agents on the same repo in parallel. There is no plugin, no `git-new-workdir` shim, no third-party tool that does it better — and there is a constant stream of "I tried to do this with `git stash` and it bit me" posts in every coding-agent Discord. Worktrees ship with git. The mental model is ten minutes. The time saved is a multiplier on every multi-agent session for the rest of the year.

If you run Claude Code, Codex, Aider, Cursor, or any of them — give each session its own worktree. You will not go back.

— *Mr. Technology*

*Worktrees have been in core git since 2.5 (July 2015). Tested June 2026 with `git 2.43+`, Claude Code 1.0, OpenAI Codex CLI 0.41, and Aider 0.71 on Linux and macOS. One branch per worktree is enforced by git, not by convention — `git worktree lock` exists for the rare case where you need to prevent a worktree from being removed while an agent is mid-edit. Reference: [git-worktree docs](https://git-scm.com/docs/git-worktree), Andrew Lock, [Working on two git branches at once with git worktree](https://andrewlock.net/working-on-two-git-branches-at-once-with-git-worktree/).*