Run parallel Claude Code sessions with git worktrees without collisions

Opening two terminals and running two Claude Code sessions in the same folder is the fastest way to… break both: session A is editing auth.ts while session B reformats it, tests run on a half-finished state, and commits get mixed up. The standard fix is a git worktree: each session gets its own checkout and branch while sharing the repo history. Claude Code supports this out of the box with the --worktree flag, creating and cleaning up worktrees for you and even blocking a session from accidentally editing the main checkout. This post walks through a safe parallel workflow.

Getting started: one command per session

# terminal 1
claude --worktree feature-auth
# terminal 2
claude -w fix-billing-bug

• The worktree is created in .claude/worktrees/<name>/, on a new branch worktree-<name>.
• Leave out the name and Claude picks one (like bright-running-fox).
• The repo needs at least one commit; add .claude/worktrees/ to .gitignore.
• To work on a PR: claude --worktree "#1234" fetches that PR into a pr-1234 worktree.

Preparing the worktree environment

A worktree is a clean checkout, so it's missing node_modules and gitignored files like .env. Two things to do:

1. Ask Claude to install dependencies at the start of the session (or run setup yourself in the worktree folder).
2. Create a .worktreeinclude file at the repo root, using .gitignore syntax, listing ignored files to copy into every new worktree:

.env
.env.local
config/secrets.json

Only files that match a pattern and are gitignored are copied, so tracked files are never duplicated.

Base branch: fresh or head?

Cleanup on exit

• A clean worktree (no changes, no new commits) from an unnamed session: the folder and branch are removed automatically.
• Changes or commits: Claude asks whether to keep or remove it. If you keep it, return later with the claude --worktree <name> --resume command printed on exit.
• Non-interactive runs (-p) have no exit prompt, so clean up yourself with git worktree remove.

One worktree per subagent

For bulk edits across many files, let subagents run in their own worktrees so parallel edits don't overwrite each other. Add isolation: worktree to the subagent's frontmatter:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor, run the tests and report results.

A subagent's worktree is removed automatically if it made no changes; with changes, it's kept until it can be cleaned up safely.

How Claude Code protects you

While a session is inside a worktree, Claude Code blocks edits targeting the main checkout, commands whose working directory is the main checkout, and git commands "redirected" back to it (git -C, GIT_DIR…). Note: shell commands that write files directly (like cp) aren't blocked by these checks; they follow your normal permissions and sandbox.

Risks and caveats

• Each worktree is a full copy of the code: installing dependencies several times costs disk and time.
• Two sessions editing the same area will still conflict at merge time; worktrees only stop them overwriting each other while working.
• Repos using Git LFS installed with --local: the worktree contains pointer files, run git lfs pull.
• More parallel sessions = more parallel tokens; watch your limits.

How to apply it

• Dev: A long feature in terminal 1, small bugs in terminal 2 with -w. Create a .worktreeinclude today.
• Tech Lead: Standardise worktree names on tickets (-w JIRA-123) and one small PR per worktree for easier review.
• PM: Split the backlog into tasks that don't touch the same files. The less they overlap, the more can run in parallel.