# Tool Description: EnterWorktree ## Metadata - Request location: `tools[]` - Tool name: `EnterWorktree` - Input schema properties: `name`, `path` ## Description 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`. ## Input Schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "Optional name for a new worktree. Each \"/\"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided. Mutually exclusive with `path`.", "type": "string" }, "path": { "description": "Path to an existing worktree of the current repository to switch into instead of creating a new one. Must appear in `git worktree list` for the current repo. Mutually exclusive with `name`.", "type": "string" } }, "additionalProperties": false } ``` ## Token Impact - Complete definition estimated tokens: **1,301** - Measurement: captured tool object serialized independently as JSON text against the common baseline - Additivity: independent, non-additive estimate