DEV Community

Cover image for Git Worktree Explained: Run Coding Agents in Parallel (and the Catch)
kush_exe
kush_exe

Posted on Originally published at kuzscotech.github.io

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

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.

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

Command What 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 list Lists 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 prune Clears 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
Enter fullscreen mode Exit fullscreen mode

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.

An urgent fix mid-refactor

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)

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

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

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)

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)

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

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)

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

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

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.

Sources

Read the full transcript, with every source, on the page for this video. More explainers like this one are on the Kush_EXE YouTube channel.

This article is built from the video's script and published sources. The video uses AI illustrations.

Top comments (0)