Run Parallel Claude Sessions Without Code Conflicts

Two terminals, two Claude sessions, same repo. One is building a feature, the other is fixing a bug. Without isolation, they'd be editing the same files and stepping on each other's changes. One flag fixes this:

claude --worktree feature-auth

Key Takeaways

• --worktree (or -w) starts Claude in an isolated git worktree with its own files and branch
• Edits in one session never touch files in another — run as many parallel sessions as you have terminals
• Worktrees live under .claude/worktrees/ and clean themselves up when unchanged
• A .worktreeinclude file copies your gitignored .env files into each new worktree
• Subagents can get their own worktrees too, with one line of frontmatter

Why not just two terminals in the same folder?

A git worktree is a separate working directory with its own checked-out branch, sharing the same repository history. Claude session A edits files in worktree A; session B edits worktree B. No collisions, no "wait, who changed this file?", and each session commits to its own branch.
I used to coordinate parallel sessions by telling each one "only touch the src/api folder." That works until it doesn't. Worktrees make the boundary physical instead of verbal.

The basic workflow

Start your first isolated session:

claude --worktree feature-auth
Open a second terminal and start another:
claude --worktree bugfix-123
Each gets a directory under .claude/worktrees/<name>/ on a new branch named worktree-<name>. Omit the name and Claude generates one like bright-running-fox.
You can also just ask Claude mid-session to "work in a worktree" — it creates one on the spot.
✅ Working correctly looks like: git worktree list shows your main checkout plus one entry per active session, each on its own branch.

Details that save you a headache later

💡 Your .env files aren't there by default. A worktree is a fresh checkout, so gitignored files don't come along. Create a .worktreeinclude file at the project root listing them (same syntax as .gitignore) and they're copied into every new worktree automatically.
💡 Worktrees branch from origin/HEAD by default, not your current branch. If you want them to carry your in-progress work, set worktree.baseRef to "head" in settings.
💡 You can branch from a PR directly: claude --worktree "#1234" fetches that pull request and creates the worktree from it. Handy for reviewing someone's PR without disturbing your own work.
💡 Add .claude/worktrees/ to .gitignore so worktree contents don't show up as untracked files in your main checkout.
⚠️ 🔍 From the docs: run plain claude once in a new directory before using --worktree there. The flag exits with an error until you've accepted the workspace trust dialog.

Cleanup is mostly automatic

Exit a session with no changes and the worktree removes itself. If there are uncommitted changes or new commits, Claude asks whether to keep or discard. Remember each worktree needs its own dependency install — node_modules doesn't come along for the ride.

Isolating subagents the same way

The same mechanism works one level down: ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter. Each subagent then edits in its own temporary worktree, which disappears automatically if it finishes without changes. This is how you let three subagents refactor three modules simultaneously without a single merge conflict.

What it doesn't solve

❌ Worktrees isolate files, not coordination. Two sessions can still do conflicting work on the same problem — they just won't corrupt each other's files while doing it. For coordinated parallel work, look at agent teams.
❌ Not a git replacement: merging the branches back is still your job.
Full reference: Worktrees — Claude Code Docs.