claude-code-system-prompts/system-prompts/tool-description-enterworktree.md

Use this tool ONLY when explicitly instructed to work in a worktree — either by the user directly, or by project instructions (CLAUDE.md / memory). This tool creates an isolated git worktree and switches the current session into it.

When to Use

• The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
• CLAUDE.md or memory instructions direct you to work in a worktree for the current task

When NOT to Use

• The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
• The user asks to fix a bug or work on a feature — use normal git workflow unless worktrees are explicitly requested by the user or project instructions
• Never use this tool unless "worktree" is explicitly mentioned by the user or in CLAUDE.md / memory instructions

Requirements

• Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
• Must not already be in a worktree session when creating a new worktree (name); switching into another existing worktree via path is allowed

Behavior

• In a git repository: creates a new git worktree inside .claude/worktrees/ on a new branch. The base ref is governed by the worktree.baseRef setting: fresh (default) branches from origin/; head branches from your current local HEAD
• Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
• Switches the session's working directory to the new worktree
• Use ExitWorktree to leave the worktree mid-session (keep or remove). On session exit, if still in the worktree, the user will be prompted to keep or remove it

Entering an existing worktree

Pass path instead of name to switch the session into a worktree that already exists (e.g., one you just created with git worktree add). The path must appear in git worktree list for the current repository — paths that are not registered worktrees of this repo are rejected. ExitWorktree will not remove a worktree entered this way; use action: "keep" to return to the original directory.

Switching with path also works when the session is already in a worktree (the previous worktree is left on disk, untouched, and only the new one is tracked for exit-time cleanup), and from agents whose working directory was pinned at launch (subagent isolation or explicit cwd). In both cases the target must be a worktree under .claude/worktrees/ of the same repository, and from a pinned agent the switch only affects this agent, not the parent session. After a further switch, previously-visited worktrees are no longer writable — re-issue EnterWorktree with path to return to one.

Parameters

• name (optional): A name for a new worktree. If neither name nor path is provided, a random name is generated.
• path (optional): Path to an existing worktree of the current repository to enter instead of creating one. Mutually exclusive with name.