Kush_EXE

Git Worktree Explained: Run Coding Agents in Parallel (and the Catch)

· Runs 2:51

git worktree explained: one repository, several folders, each with its own branch checked out at once. We follow the example in git's own manual (an urgent fix in the middle of a messy refactor, without git stash), show why a worktree is not a second clone, and cover the rule you'll hit first: a branch checked out in one folder is refused in another unless you force it.

Then the same folders go to coding agents: claude --worktree in Claude Code, two sessions working in parallel, and subagents with isolation: worktree. We also cover the catches the docs admit. A worktree is a fresh checkout with no dependencies and no .env, the disk space adds up, ports, databases and Docker are still shared, submodule support is incomplete, and you can still only review one big change at a time.

Watch on YouTube Subscribe

Cheat sheet

What a git worktree is

A git worktree is an extra folder attached to the same repository, so you can check out more than one branch at once. Use it when an urgent fix turns up mid-refactor, or when several coding agents each need their own folder.

It is not a second clone: worktrees share history, branches and config; each keeps its own HEAD and index.

Everyday commands

CommandWhat it does
git worktree add -b <new-branch> <path> <start>New folder on a new branch from <start>
git worktree add <path> <branch>New folder on an existing branch
git worktree listLists each worktree's path, commit and branch
git worktree remove <path>Removes a clean worktree folder (never the main one)
git worktree remove --force <path>Removes it despite untracked or modified files
git worktree pruneClears records of worktree folders deleted by hand

Example: urgent fix mid-refactor

# in your project folder; main = your base branch
git worktree add -b emergency-fix ../temp main
pushd ../temp
# fix the bug
git commit -a -m "emergency fix"
popd
git worktree remove ../temp
git branch

Adapted from git's manual, which uses master. In the video's demo run, unfinished changes in the main folder stayed untouched, and the emergency-fix branch and commit survived the remove.

Gotchas

  • One branch, one folder. git worktree add refuses a branch already checked out in another worktree, unless you pass --force.
  • A worktree is a fresh checkout. Dependencies and gitignored files such as .env are missing. Cursor's docs advise against symlinking dependencies and suggest a fast package manager such as pnpm.
  • Disk adds up. OpenAI's Codex docs warn worktrees can take up a lot of disk space. One Cursor user with a ~2 GB codebase reported about 140 GB from 20+ automatic worktrees in a week (not a benchmark).
  • Only files are isolated. Upsun's vendor blog notes worktrees share dev-server ports, the local database and Docker, so parallel agents can collide.

With Claude Code

claude --worktree <name> (or -w) creates .claude/worktrees/<name>/ on a new branch worktree-<name>. A .worktreeinclude file, in gitignore syntax, copies the gitignored files you list into each worktree Claude Code creates.

Limits

  • Repositories with submodules. Git's manual still calls multiple checkouts experimental and submodule support incomplete, and recommends against multiple checkouts of a superproject.
  • It won't speed up review. Simon Willison runs agents in parallel, yet says he can only focus on reviewing and landing one significant change at a time.

Sources: git manual, Claude Code docs.

This cheat sheet as plain Markdown

In this video

  1. An urgent fix mid-refactor
  2. What a git worktree is (git worktree add)
  3. Not a second clone: what's shared, what's not
  4. Fix, commit, remove, and the one-branch rule
  5. Coding agents in parallel (claude --worktree)
  6. The catch: a fresh checkout (.env, dependencies)
  7. Worktrees and disk space
  8. What worktrees don't isolate (ports, Docker, submodules)
  9. More agents, still one review at a time
  10. Cleanup checklist and recap

An urgent fix mid-refactor 0:00

Mid-refactor, your code is torn apart, and a fix can't wait. Stashing that mess feels risky. Git's own manual describes this moment, and its answer isn't stash.

What a git worktree is (git worktree add) 0:11

It's called a git worktree: one repository, several folders, each with its own branch checked out at once. You run git worktree add, dash b, emergency-fix, dot-dot-slash temp, master, and a new folder called temp appears next to your project.

Not a second clone: what's shared, what's not 0:27

It's not a second clone. Its .git is just a small file pointing back to your main repository. Every worktree shares the history and branches. Each keeps its own HEAD and index: which branch it's on, and what's staged.

Fix, commit, remove, and the one-branch rule 0:41

You fix the bug there, commit, and remove the folder. Your half-finished refactor never moved. And when we ran it, the fix survived too: removing the folder kept the branch and its commit. There's one rule you'll hit first: a branch checked out in one folder gets refused in a second, unless you force it.

Coding agents in parallel (claude --worktree) 0:59

Now hand those extra folders to coding agents. Boris Cherny, who created Claude Code, announced built-in support: "Each agent gets its own worktree and can work independently." Type claude, dash dash worktree, feature-auth. Claude Code makes a folder in your repo on a new branch, worktree-feature-auth. Run it again in a second terminal with another name, and one session builds a feature while the other fixes a bug. Subagents can do it too. Add isolation: worktree to a custom subagent's frontmatter, and it gets its own temporary worktree.

The catch: a fresh checkout (.env, dependencies) 1:33

Here's the catch, in Anthropic's words: "A worktree is a fresh checkout." Your dependencies aren't there, and neither is your .env. In Claude Code, a .worktreeinclude file copies the gitignored files you list, like .env, into each new worktree. For installs, Cursor's docs say don't symlink dependencies; use a fast package manager like pnpm.

Worktrees and disk space 1:55

That costs disk. Codex's docs warn worktrees can take a lot of space, and one Cursor user found about 140 gigabytes in twenty-plus automatic worktrees piled up over a week.

What worktrees don't isolate (ports, Docker, submodules) 2:07

And worktrees isolate files, not your machine. Two agents can still collide on the same port, local database or Docker. Using submodules? Git's own manual calls that support incomplete, and recommends against multiple checkouts of a superproject.

More agents, still one review at a time 2:22

More agents don't mean more you can review. Simon Willison runs several at once and still says, "I can only focus on reviewing and landing one significant change at a time."

Cleanup checklist and recap 2:32

So give each task its own worktree, check git worktree list, and remove what's done. Git only removes clean ones unless you force it. One branch per folder, one folder per agent. Worktrees isolate your files, not your disk space or your review time.

What the sources say

  • Git's manual says a repository can support multiple working trees, so more than one branch can be checked out at a time. Each extra one is called a linked worktree, as opposed to the main worktree made by git init or git clone. Git project
  • A linked worktree is not a second clone. According to Git's manual it shares everything with the repository except per-worktree files such as HEAD and the index, and refs are shared across all worktrees except refs/bisect, refs/worktree and refs/rewritten. Git project
  • The command git worktree add refuses to create a worktree for a branch that is already checked out in another worktree unless --force is passed. OpenAI's Codex documentation states the same rule: Git only allows a branch to be checked out in one place at a time. Git project, OpenAI
  • Git's manual gives an example for an urgent fix in the middle of a refactor: instead of git stash, a temporary linked worktree is created with git worktree add -b emergency-fix ../temp master, the fix is committed there, and git worktree remove ../temp removes it before the refactor resumes. Git project
  • Anthropic's Claude Code documentation says claude --worktree (or -w) followed by a name creates an isolated worktree, by default under .claude/worktrees/ in a folder with that name, on a new branch called worktree- plus the name. Running it again with another name in another terminal starts a second isolated session. Anthropic
  • Anthropic's Claude Code documentation describes a worktree as a fresh checkout: dependencies have to be installed again in it, and gitignored files such as .env are not there. A .worktreeinclude file, written in .gitignore syntax, copies matching gitignored files into each new worktree. Anthropic
  • OpenAI's Codex documentation warns that worktrees can take up a lot of disk space, as each has its own repository files, dependencies and build caches. One Cursor user on Windows reported on its forum on December 13, 2025 that 20 or more automatic worktrees grew to about 140 GB in a week, for a codebase of about 2 GB. OpenAI, Cursor Community Forum
  • Anthropic's Claude Code documentation says worktrees isolate file edits. A vendor blog post from Upsun adds that agents in separate worktrees still share the local database, the Docker daemon and cache directories, and that dev servers default to the same ports, so two agents can still collide. Anthropic, Upsun
  • Git's manual states that support for submodules in multiple checkouts is incomplete, and it recommends against making multiple checkouts of a superproject. Git project
  • Simon Willison, who runs several coding agents in parallel, wrote on October 5, 2025 that he can only focus on reviewing and landing one significant change at a time. Simon Willison's Weblog

Sources

  1. git-worktree - Manage multiple working trees Git project
  2. Git 2.5, including multiple worktrees and triangular workflows GitHub Blog
  3. Run parallel sessions with worktrees Anthropic
  4. Common workflows Anthropic
  5. Introducing: built-in git worktree support for Claude Code Boris Cherny on X
  6. Worktrees Cursor
  7. Motivation pnpm
  8. Worktrees OpenAI
  9. Windows: Request to disable automatic worktree creation - critical disk space issue Cursor Community Forum
  10. Git worktrees for parallel AI coding agents Upsun
  11. Embracing the parallel coding agent lifestyle Simon Willison's Weblog