EnterWorktree tool description
SDK-CLI Agent SDK, print mode, v2.1.281. The text the model is given for this tool, line by line, with each line marked against the previous capture taken the same way. One model string produces this prompt.
As described in the system reminder: claude md request, not the ordinary one.
Lines363,220 characters
Moved+0−0 against v2.1.280
Sent to1model strings get this description
Copies1distinct descriptions under this name
Parameters20 of them required
Every tool→every description on this arm
Plain text · sha256 6e2930159e8f
The description, line by line
36 lines Line numbers are v2.1.280 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"
}