Claude Code Worktrees: Run Parallel Sessions Without Collisions

Pass --worktree (or -w) with a name:

1# terminal 12claude --worktree feature-auth3 4# terminal 25claude --worktree fix-login

Each command creates .claude/worktrees/<name>/ at the repository root, on a new branch named worktree-<name>, and starts Claude there. Omit the name and Claude generates one, such as bright-running-fox. Passing a name whose directory already exists reopens that worktree instead of creating a new one.

You can also ask Claude mid-session to "work in a worktree", and it creates one with the EnterWorktree tool. Entering a path outside .claude/worktrees/ always asks for your approval first, because it moves the session's working directory, write access, and project configuration there.

Two setup steps matter. Add .claude/worktrees/ to .gitignore so worktree contents never show as untracked files in the main checkout. And remember that interactive --worktree runs need workspace trust: run plain claude once in a new directory to accept the trust dialog, or --worktree exits with an error. claude -p --worktree skips the trust check.

A worktree is a fresh checkout of tracked files. It has no node_modules, no virtual environment, no build output, and none of your gitignored local files. Ask Claude to install dependencies first, or run your setup command in the worktree.

For gitignored files you need everywhere, such as .env, add a .worktreeinclude file at the project root. It uses .gitignore syntax, and only files that match a pattern and are gitignored are copied into each new worktree, so tracked files are never duplicated:

1.env2.env.local3config/secrets.json

It applies to every worktree Claude Code creates with git: --worktree sessions, subagent worktrees, and desktop-app parallel sessions. With a WorktreeCreate hook, it is not processed; copy the files in your hook script.

Two practical consequences of separate checkouts: each worktree needs its own dependency install (time and disk), and if two worktrees start dev servers they need different ports. Tell Claude which port to use in each session, or configure your dev server to pick a free one.

When you exit an interactive worktree session, Claude checks the worktree for work removal would delete: changed or untracked files, uncommitted work in submodules, and new commits.

• Clean: for an unnamed session, Claude removes the worktree and its branch automatically. A named session asks first, so you can keep it.
• Has work: Claude asks whether to keep or remove it. Keeping preserves the directory and branch, and Claude prints the claude --worktree <name> --resume command to return. Removing deletes the directory, the branch, and everything in them.
• Cannot verify: Claude asks rather than deleting anything, and names what it could not check.

Non-interactive claude -p runs have no exit prompt, so their worktrees are never cleaned up automatically. Remove them with git worktree remove, after git worktree unlock if git says the worktree is locked.

Resuming a session that ended inside a worktree returns it to that worktree, for interactive resumes, --continue and --resume with -p, and the Agent SDK. If the worktree was deleted, the session resumes in your launch directory and tells you. Resume from the main checkout when in doubt; some worktrees are only re-entered from there.

While a session is isolated in a worktree, Claude Code applies four checks, including to every subagent the session spawns:

1. File edits: Edit, Write, and NotebookEdit calls that target the main checkout are blocked. 2. Command working directory: a Bash, PowerShell, or Monitor command whose working directory resolves to the main checkout, or cannot be verified to stay out of it, is blocked. 3. Git redirects: commands that point git at the main checkout through git -C, --git-dir, GIT_DIR or GIT_WORK_TREE, or a cd first, are blocked. 4. Command shape: commands whose git usage cannot be verified from the text, such as computed command names or unparseable syntax, are blocked, and Claude is told how to rewrite them. This check cannot be turned off.

The limit is stated plainly in the docs: these checks read paths, directories, and command text, and none tracks which files a shell command writes. A cp into the main checkout or a shell redirect such as echo x > ../main/file is not refused by them; it falls under your normal permission rules and sandbox settings.

Hooks also need care. ${CLAUDE_PROJECT_DIR} stays pointed at the project root where the session started, while the cwd field in the hook's JSON input follows Claude into the worktree. A hook that should act on the files Claude is editing must read cwd.

Subagents can each run in their own worktree so parallel edits inside one session do not collide. Ask Claude to "use worktrees for your agents", or make it permanent for a custom subagent with isolation: worktree in its frontmatter:

1---2name: refactorer3description: Applies mechanical refactors across many files4isolation: worktree5---6 7Apply the requested refactor across every affected file, then run the tests8and report the results.

Each subagent gets a temporary worktree. Claude Code removes it automatically when the subagent finishes without changes; one with changes stays until a periodic sweep can remove it without losing work, based on your cleanupPeriodDays setting. While an agent runs, Claude Code holds a git worktree lock on its worktree so cleanup cannot remove it mid-task.

A subagent in its own worktree takes its instruction files from your main conversation. When the worktree is in the default location, it does not load the worktree branch's own CLAUDE.md or .claude/rules/, even if they differ.

By default, new worktrees branch from the repository's default branch on the remote (worktree.baseRef: "fresh"), so each starts clean and matching origin. If the repository has not been fetched in 24 hours, Claude Code fetches the default branch first (capped at five seconds) and falls back to the cached ref. To branch from your current local HEAD instead, including unpushed commits, set:

1{2  "worktree": {3    "baseRef": "head"4  }5}

baseRef cannot name a branch. To start from a specific existing branch, or to put the worktree outside the repository, use git directly:

1git worktree add ../project-feature-a -b feature-a   # new branch2git worktree add ../project-bugfix fix-issue-456     # existing branch3cd ../project-feature-a && claude4git worktree list5git worktree remove ../project-feature-a

Worktrees you create this way get the same sharing (plugins, approvals, untracked skills read-through), but Claude Code's automatic cleanup never removes them.

Most worktree problems are about git identity. Claude Code checks that a worktree really is a separate checkout before using it, because a directory whose git metadata points back into the main checkout would let an ordinary git reset --hard destroy work there. When it refuses, it leaves the directory in place, since it may hold work, and the end of the message names the recovery.

When something looks wrong, run git worktree list from the main checkout first. It shows each worktree's path, branch, and lock state, which explains most surprises.

Use a repository with a test command.

1. Add .claude/worktrees/ to .gitignore and create .worktreeinclude containing .env. 2. In two terminals, run claude -w add-validation and claude -w update-docs, and give each a small task. 3. In each, run git status and git branch --show-current. Confirm separate files and branches. 4. In the first session, ask Claude to run echo test > ../../../scratch.txt (a new file in the main checkout) and see whether it is blocked or falls to a permission prompt. 5. Create .claude/agents/refactorer.md with isolation: worktree and ask Claude to use it for a rename across three files. 6. Exit both sessions; keep one worktree and remove the other. Run git worktree list.

Pass criterion: the sessions never saw each other's changes, the subagent worked in its own worktree, and git worktree list shows exactly the worktrees you chose to keep.