Two Claude Code sessions editing the same checkout will step on each other’s files. A git worktree is a separate working directory on its own branch that shares the repository history — so one session can build a feature while another fixes a bug, and neither sees the other’s edits. Claude Code creates and cleans these up for you.
1. Start Claude in a worktree
From the root of a repository that has at least one commit:
claude --worktree feature-auth
Creates .claude/worktrees/feature-auth/ on a new branch worktree-feature-auth and starts Claude inside it. -w is the short flag; omit the name and Claude invents one like bright-running-fox.
The first interactive run in a directory needs workspace trust — if --worktree exits asking for it, run plain claude there once, accept the dialog, then retry.
2. Start a second session
In another terminal, same repository:
claude --worktree fix-login-bug
That’s the whole trick: each terminal owns a worktree, each worktree owns a branch. While a session is isolated, Claude Code blocks edits and git commands that would reach back into the main checkout, and tells Claude how to rewrite a refused command.
Keep the worktree folders out of git status:
echo ".claude/worktrees/" >> .gitignore
3. Carry your .env into every worktree
A worktree is a fresh checkout, so gitignored files such as .env aren’t there. List them in a .worktreeinclude file at the project root (gitignore syntax; only files that are also gitignored get copied):
.env
.env.local
config/secrets.json
Dependencies are not copied — ask Claude to run your install step, or run npm install / uv sync yourself inside .claude/worktrees/<name>/.
4. Branch from a pull request instead
Quote the argument so the shell doesn’t read # as a comment:
claude --worktree "#1234"
Fetches that PR’s head from origin and creates the worktree at .claude/worktrees/pr-1234. A GitHub PR URL or GitLab MR URL works too.
5. Clean up
When you exit an interactive worktree session, Claude checks for uncommitted work and new commits. A clean, unnamed session’s worktree is removed automatically; if there is work in it, you’re asked whether to keep or remove it. Non-interactive -p runs never prompt, so remove those yourself:
git worktree list
git worktree remove .claude/worktrees/feature-auth
--force removes a worktree that still has uncommitted changes; if git says the worktree is locked, run git worktree unlock <path> first.
Worth knowing
- New worktrees branch from the repository’s default branch (
mainon the remote). To branch from your current localHEADinstead — say, to isolate a subagent on in-progress work — set{"worktree": {"baseRef": "head"}}insettings.json. - Reusing a name (
claude --worktree feature-authagain) reopens the existing worktree rather than creating a new one. - Subagents can get their own worktrees: add
isolation: worktreeto a custom agent’s frontmatter in.claude/agents/.
Next: use subagents · run Claude Code headless in a script or CI.