Claude Code Worktrees: Run Parallel Sessions Safely

A Claude Code worktree is a separate copy of your repository's files on its own branch, so two Claude sessions can work at once without overwriting each other. Start one with claude --worktree <name>. It's created under .claude/worktrees/, on a new branch, and removed when you exit if nothing changed.

This guide covers starting worktree sessions, getting .env files into them, cleaning up, isolating subagents and when parallel work is worth it. Checked against Claude Code's worktrees docs, October 2026.

code.claude.com/docs/en/worktrees

Why worktrees

Without them, two Claude sessions in the same folder edit the same files. One session's half-finished change breaks the other's tests, and you can't tell whose edit caused what.

A git worktree is a separate working directory with its own files and branch, sharing the same repository history. Each session gets its own copy to edit, so one can build a feature while another fixes a bug.

Your git repository keeps one history, and you get one set of files per worktree. Worktrees need a git repository, and each one is a fresh checkout, so install dependencies per worktree.

Start a session in a worktree

claude --worktree booking-fix

Or the short form, claude -w booking-fix. By default this creates .claude/worktrees/booking-fix/ at the repository root, on a new branch called worktree-booking-fix. Run the same command with a different name in another terminal to start a second isolated session. Leave out the name and Claude generates one.

Two setup notes from the docs:

• Add .claude/worktrees/ to .gitignore so worktree contents don't show up as untracked files in your main checkout.
• Trust the folder first. If you've never run Claude in the repository, run claude there once to accept the trust prompt.

You can also ask Claude mid-session to "work in a worktree" and it creates one. In the desktop app, choose the worktree option when starting a session.

Get .env files into the worktree

A worktree is a fresh checkout, so gitignored files such as .env aren't there. Add a .worktreeinclude file at the project root, in .gitignore syntax, listing what to copy:

.env
.env.local

Only files that match a pattern and are gitignored get copied. Then ask Claude to install dependencies in the new worktree, since node_modules won't be there either.

Choose the base branch

New worktrees branch from your repository's default branch on the remote, usually main, so each one starts clean. To carry unpushed commits into the worktree, set worktree.baseRef to "head" in your settings. You can't set it to a branch name.

Create a worktree with git

When you need a specific existing branch, or a folder outside the repository, use git directly:

git worktree add ../project-bugfix fix-issue-456

Then run claude inside that folder. List your worktrees with git worktree list, and remove one with git worktree remove ../project-bugfix when you're done.

Clean up when you're done

When you exit a worktree session, Claude checks it for work:

• Nothing changed: an unnamed session's worktree and branch are removed automatically. A named session asks first.
• There's work in it: Claude asks whether to keep or remove it. Keep it to come back later with the claude --worktree <name> --resume command it prints.

To remove one yourself, use git worktree remove. List them with git worktree list.

Branch from a pull request

To work on someone's pull request in isolation:

claude --worktree "#1234"

Quote the argument so your shell doesn't treat # as a comment. Claude fetches the pull request's head commit and creates .claude/worktrees/pr-1234.

Isolate subagents too

Subagents can each get their own worktree, so parallel edits inside one session don't conflict either. Ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter. Claude removes a subagent's worktree automatically when it finishes without changes.

A parallel workflow for client work

1. Main checkout: your planning and review. Nothing is built here.
2. Worktree 1: the feature the client asked for.
3. Worktree 2: a bug fix from the client's issue list.
4. Each worktree finishes with a pull request. You review them one at a time, check each preview, and merge. See using Claude Code with GitHub.

Keep it to two or three at once. Each session needs your review, and reviewing is the bottleneck, not Claude's speed.

When not to bother

• Small, sequential tasks: one session is simpler.
• Changes that depend on each other: finish one, merge it, then start the next.
• Projects with heavy setup per checkout (large dependencies, local databases): the setup time can outweigh the benefit.

Learn to build with Claude Code

The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls. The free guide library includes a guide to running agents in parallel.

FAQ

What are worktrees in Claude Code?

A worktree is a separate working copy of your repository on its own branch. Claude Code can start a session in one with --worktree, so several sessions can edit the same project in parallel without overwriting each other's files.

What's the difference between a worktree and a branch?

A branch is a line of history. A worktree is a folder on disk with a branch checked out. Normally you have one folder and switch branches in it. With worktrees, each branch has its own folder, so two sessions can work on two branches at the same time.

Can I run multiple Claude Code sessions in parallel?

Yes. Start each one in its own worktree with claude --worktree <name> in a separate terminal, or use the worktree option in the desktop app. Each gets its own files and branch, and you merge the results one at a time.

Do worktrees copy my .env file?

Not by default, because a worktree is a fresh checkout and .env is usually gitignored. Add a .worktreeinclude file listing the gitignored files to copy, such as .env and .env.local.