The description, rendered
This renders the markdown inside the description, so it isn’t quite the description itself.The raw view and the plain text are the bytes as they were sent.
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 viapathis allowed
Behavior
- In a git repository: creates a new git worktree inside
.claude/worktrees/on a new branch. The base ref is governed by theworktree.baseRefsetting:fresh(default) branches from origin/<default-branch>;headbranches 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). On first entry from the launch directory, the path must appear in git worktree list for the repository that owns it — the current repository or, in a multi-repo workspace, a repository nested inside it; paths registered by neither 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 neithernamenorpathis provided, a random name is generated.path(optional): Path to an existing worktree to enter instead of creating one — of the current repository, or (on first entry from the launch directory) of a repository nested inside it. Mutually exclusive withname.
What it accepts
2 parameters The JSON parameter schema sent beside this description, 741 characters of it. Name, type, then whether the client marked it required.name
string
optional
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`.
path
string
optional
Path to an existing worktree to switch into instead of creating a new one. Must appear in `git worktree list` for the current repo — or, on first entry from the launch directory, for a repo nested inside it (multi-repo workspace). Mutually exclusive with `name`.
sha256 7fba3c925332 · the schema as the client sent it: