Three claude --worktree Features That Make Parallel Claude Code Development Click

TL;DR: The native --worktree flag creates an isolated branch session in one command; combine it with .worktreeinclude, PR numbers, and subagent frontmatter to eliminate parallel Claude Code setup friction.

Building on the basic parallel-worktree pattern, Claude Code's native --worktree flag has three lesser-known features that remove most of the setup friction:

1. Open any PR in isolation

claude --worktree "#1234"

Claude Code fetches pull/1234/head from origin, creates .claude/worktrees/pr-1234, and opens a session on that branch. Review code, run the test suite, apply a fix — all isolated from your main checkout. The worktree is removed automatically when you exit if you made no changes. No branch juggling, no stash, no risk of uncommitted changes mixing.

2. Auto-copy .env into every worktree

Worktrees start as bare checkouts — gitignored files like .env aren't present, so your dev server fails immediately on launch. Fix it once with a .worktreeinclude file at your repo root:

.env
.env.local
config/secrets.json

Any file that matches a pattern AND is gitignored gets copied into each new worktree automatically — including --worktree sessions, subagent worktrees, and desktop app parallel sessions.

3. Branch subagents from your current work

By default, --worktree branches from origin/HEAD (the remote default branch). When you need subagents to operate on your in-progress commits and feature branch state, add one field to .claude/settings.json:

{ "worktree": { "baseRef": "head" } }

Or add isolation: worktree to a custom subagent's frontmatter — each invocation gets its own worktree branched from your current state, cleaned up automatically when the agent finishes without changes.

Sources: Run parallel sessions with worktrees — Claude Code Docs