Once you get comfortable with an AI coding agent, you hit a natural next thought: why run just one? Why not have Claude fixing a bug in one session while another builds a feature and a third writes tests? The obstacle is immediate and messy: they'd all be editing the same files in the same directory, stepping on each other constantly. Git worktrees are the clean solution, and Claude Code has built-in support for them.
What a worktree is
A git worktree is a separate working directory that shares the same repository history. Normally a repo has one working directory checked out to one branch. Worktrees let you have several checkouts of the same repo at once, each on its own branch, each with its own copy of the files — all backed by the one shared .git history. Edits in one worktree don't touch the files in another.
Run a Claude session inside its own worktree and it's isolated: it can edit, build, and run freely without any risk of colliding with a session working elsewhere. That's what makes safe parallelism possible.
Spinning one up
Claude Code makes worktrees a first-class feature:
- From the command line:
claude --worktree feature-authcreates a worktree (under.claude/worktrees/) on a fresh branch and starts the session there. Omit the name —claude --worktree— and it generates one for you. - Mid-session: you can ask Claude to move its work into a worktree, and it'll create one on the spot.
- For subagents: set
isolation: worktreein a subagent's frontmatter, and that subagent runs in its own isolated worktree — the mechanism that lets multiple agents mutate files in parallel without conflict. - From a PR:
claude --worktree "#1234"checks out a worktree for that pull request.
By default a new worktree branches from your repo's remote default (origin/HEAD), giving each session a clean starting point rather than inheriting your current uncommitted mess. (You can change that base if you'd rather branch from local HEAD.)
The gitignored-files problem
Here's the practical snag everyone hits first. A worktree is a fresh checkout, so files that git ignores — your .env, local config, secrets — don't exist in it. Your app boots in the main directory and mysteriously fails in the worktree because it can't find its environment.
The fix is a .worktreeinclude file at your project root, which uses .gitignore syntax to list the gitignored files that should be copied into new worktrees:
.env
.env.local
config/secrets.json
Only files that are both gitignored and match a pattern get copied; tracked files are never duplicated. This applies to --worktree sessions, subagent worktrees, and desktop parallel sessions alike. Note that it only handles files — dependencies don't come along, so you'll still run npm install (or your equivalent) in a fresh worktree.
Cleanup
Worktrees could pile up fast, so Claude Code manages their lifecycle:
- No changes made? When the session ends, the worktree and its branch are deleted automatically. Nothing to clean up.
- Uncommitted changes, new files, or new commits? Claude prompts you: keep the worktree (to finish or merge the work later) or discard it.
- Subagent/background worktrees are auto-removed once they're older than your configured cleanup period and have nothing unsaved in them.
- Manual control is always available:
git worktree remove <path>(add--forceif it has uncommitted changes).
One caveat: in non-interactive (-p) runs, worktrees are not auto-cleaned — there's no one to prompt — so you remove them yourself.
When to reach for it
Worktrees shine whenever you want genuine parallelism or isolation:
- Running multiple Claude sessions at once on the same repo without collisions.
- Letting a fleet of subagents each mutate files independently (the
isolation: worktreecase). - Trying a risky change in isolation so your main checkout stays pristine and you can throw the attempt away by just deleting the worktree.
The mental model is simple: a worktree is a disposable, isolated copy of your project that shares history but not files. That combination — shared history, separate files — is exactly what you need to point several AI sessions at one codebase and have them work in parallel instead of in each other's way. And because an unchanged worktree cleans itself up, the cost of spinning one up for a quick experiment is close to zero.