Cheat sheet for the video [Git Worktree Explained: Run Coding Agents in Parallel (and the Catch)](https://www.youtube.com/watch?v=m07OkAHbfaM) · [read the full page](https://kuzscotech.github.io/kush-exe/git-worktree-explained/)

## 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
```

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](https://cursor.com/docs/configuration/worktrees) advise against symlinking dependencies and suggest a fast package manager such as pnpm.
- **Disk adds up.** OpenAI's [Codex docs](https://learn.chatgpt.com/docs/environments/git-worktrees) warn worktrees can take up a lot of disk space. One [Cursor user](https://forum.cursor.com/t/windows-request-to-disable-automatic-worktree-creation-critical-disk-space-issue/146189) 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](https://developer.upsun.com/posts/ai/git-worktrees-for-parallel-ai-coding-agents) 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](https://simonwillison.net/2025/Oct/5/parallel-coding-agents/) runs agents in parallel, yet says he can only focus on reviewing and landing one significant change at a time.

Sources: [git manual](https://git-scm.com/docs/git-worktree), [Claude Code docs](https://code.claude.com/docs/en/worktrees).