Run parallel sessions with worktrees - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A git worktree is a separate working directory with its own files and branch, sharing the same repository history and remote as your main checkout. Running each Claude Code session in its own worktree gives it a separate copy of the files to edit, so one session can build a feature while a second fixes a bug.
If you use another version control system or the desktop app, follow the instructions for your setup: Other version control systems : worktrees require a git repository; configure hooks to replace the git logic Desktop app : see Run a session in its own worktree Worktrees are one of several ways to run Claude in parallel. They isolate file edits. Subagents split work up inside one session, and cross-session messaging lets Claude pass findings between the sessions in your worktrees.
See Run agents in parallel to compare the approaches, or skip ahead to Isolate subagents with worktrees to use worktrees and subagents together. Most sessions need only the first two sections: start Claude in a worktree , then clean up when you exit . Return to the rest of the page when you need to resume a session , change how worktrees are created , or debug a failure . Start Claude in a worktree Pass --worktree or -w with a name to create an isolated worktree and start Claude in it.
By default, the worktree is created under .claude/worktrees/<name>/ at your repository root, on a new branch named worktree-<name> : claude --worktree feature-auth Run the command again with a different name in another terminal to start a second isolated session. If you omit the name, Claude generates one such as bright-running-fox . Interactive runs require workspace trust : if you haven’t run Claude in the directory before, run claude once there to accept the trust dialog, or --worktree exits with an error prompting you to.
Non-interactive runs with -p skip the trust check, so claude -p --worktree proceeds without it. Add .claude/worktrees/ to your .gitignore so worktree contents don’t appear as untracked files in your main checkout. Set up the worktree environment A worktree is a fresh checkout, so initialize your development environment there: ask Claude to install dependencies, or run your project’s setup yourself in the worktree directory under .claude/worktrees/ .
To carry gitignored files such as .env into every new worktree automatically, add a .worktreeinclude file . Ask Claude to create a worktree You can also ask Claude to “work in a worktree” during a session, and it creates one with the EnterWorktree tool. Once in a worktree, Claude can switch directly to another one under .claude/worktrees/ by calling EnterWorktree with the target path; the previous worktree stays on disk untouched.
When Claude enters a path outside the repository’s .claude/worktrees/ directory, Claude Code asks for your approval first. The move takes the session’s working directory, write access, and project configuration such as CLAUDE.md and settings to that location. An EnterWorktree permission rule or choosing “don’t ask again” doesn’t suppress this prompt; only bypassPermissions mode skips it. Hook paths don’t follow the worktree.
After Claude enters a worktree, Claude Code keeps ${CLAUDE_PROJECT_DIR} in your hooks where it was and passes the worktree path to them a different way: ${CLAUDE_PROJECT_DIR} stays put : it still points at the project root where the session started, so a hook command such as ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh still runs the script in the main checkout. cwd follows Claude : the cwd field in the hook’s input JSON is the worktree root, and it moves again when Claude runs cd .
Read it when a hook needs the worktree path. Claude has no EnterWorktree tool If you ask Claude to work in a worktree and it has no EnterWorktree or ExitWorktree tool, check whether permissions.blockWritesOutsideWorkingDirectories is on. Once the key is on, Claude Code removes both worktree tools or refuses calls to them. You can keep working in worktrees while the key is on: Interactive sessions : start the session in a worktree with claude --worktree .
Background sessions : Claude Code refuses a background session’s edits in your main checkout until the session calls EnterWorktree , which it doesn’t have. Any of these lets the session edit: Start it with claude --bg --worktree Set worktree.bgIsolation to "none" Have Claude edit in a worktree made with git worktree add under the directory the session started in To get the tools back, run /status in the session to list the setting sources it loaded , and remove the key from every file that sets it.
Then restart Claude Code. If managed settings set the key, ask your administrator whether the policy should change. Clean up worktrees When you exit an interactive worktree session, Claude checks the worktree for work that removal would delete: changed or untracked files, uncommitted work inside checked-out submodules, and new commits. These rules apply to worktrees Claude created with git. For a worktree your WorktreeCreate hook created, see WorktreeRemove instead.
The worktree is clean : for an unnamed session, Claude removes the worktree and its branch automatically. A named session prompts you first so you can keep the worktree for later The worktree has work in it : Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch. To return later, run the claude --worktree <name> --resume command that Claude Code prints on exit. Removing deletes the worktree directory and its branch, along with all the work in them Another branch is checked out : if the worktree is on a branch other than its own that has commits past the worktree’s starting commit, Claude prompts you to keep or remove the worktree.
Either answer keeps that other branch and its commits. Removing deletes the worktree directory and the worktree’s own branch, the one Claude created with it The worktree’s state can’t be verified : when Claude Code can’t count the worktree’s changes or can’t inspect its submodule checkouts, it prompts you rather than removing the worktree automatically. The prompt names what it couldn’t check Non-interactive runs with -p have no exit prompt, so Claude doesn’t clean up their worktrees, and Claude Code leaves the lock it took on each one at creation in place until a later session’s stale-lock sweep releases it.
To remove one, run git worktree remove ; if git refuses because the worktree is locked, run git worktree unlock on it first. On Windows, removing a worktree doesn’t delete files outside it. If a folder inside the worktree is a link to somewhere else, such as an NTFS junction or a directory symlink, Claude Code deletes only the link. Resume a worktree session When you resume a session that ended inside a worktree without exiting it , Claude Code returns the session to that worktree.
This holds for interactive resumes, for --continue and --resume in non-interactive mode with -p , and for the Agent SDK. --continue picks the most recent session recorded under the directory you launch from. Back inside the worktree, Claude can leave with the ExitWorktree tool when the session has that tool . Before returning the session to its worktree, Claude Code verifies that the worktree is still a checkout separate from the main one, and declines to re-enter a worktree that fails the check.
For a git worktree, the check reads its git metadata. A worktree without git metadata, such as one a WorktreeCreate hook created, can pass the check; the cases Claude Code still refuses are listed with their recoveries under Claude Code refuses to use a worktree . For the messages and how to recover from each, see The session resumes outside its worktree
The rest of this page is on the live site.