Plain text · sha256 6e2930159e8f
The description, line by line
36 lines Line numbers are v2.1.277 on the left and this capture on the right.
1
1
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.
2
2
3
3
## When to Use
4
4
5
5
- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
6
6
- CLAUDE.md or memory instructions direct you to work in a worktree for the current task
7
7
8
8
## When NOT to Use
9
9
10
10
- The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
11
11
- 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
12
12
- Never use this tool unless "worktree" is explicitly mentioned by the user or in CLAUDE.md / memory instructions
13
13
14
14
## Requirements
15
15
16
16
- Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
17
17
- Must not already be in a worktree session when creating a new worktree (`name`); switching into another existing worktree via `path` is allowed
18
18
19
19
## Behavior
20
20
21
21
- 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/<default-branch>; `head` branches from your current local HEAD
22
22
- Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
23
23
- Switches the session's working directory to the new worktree
24
24
- 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
25
25
26
26
## Entering an existing worktree
27
27
28
28
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.
29
29
30
30
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.
31
31
32
32
## Parameters
33
33
34
34
- `name` (optional): A name for a new worktree. If neither `name` nor `path` is provided, a random name is generated.
35
35
- `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 with `name`.
36
36
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:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"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 to switch into instead of creating a new one. Must appear in `git worktree list` for the current repo \u2014 or, on first entry from the launch directory, for a repo nested inside it (multi-repo workspace). Mutually exclusive with `name`.",
"type": "string"
}
},
"type": "object"
}