A second checkout of the repository, on its own branch, in its own directory — created and torn
down through the EnterWorktree / ExitWorktree tools.
The Gate: Explicit Instruction Only
Exactly one thing authorizes EnterWorktree: the word "worktree" appearing explicitly in the
user's request, or in project instructions (CLAUDE.md / memory). Per the tool's own contract,
never reach for it because work merely looks isolated, risky, experimental, or parallel.
If you got here from any of the following, stop and do the other thing instead:
| If the trigger was… | Do this instead |
|---|---|
| "fix this bug", or a hotfix, without the word "worktree" | Normal git workflow — branch, fix, commit |
| Investigating a bug or testing a hypothesis | Investigate in place; undo with git checkout -- <file> |
| "do this in isolation" / "experiment in isolation" | An ordinary branch or a scratch copy — isolation alone is not a worktree trigger |
| Parallel sub-agents, parallel tool calls, concurrent tasks | Unrelated to worktrees. For per-agent repo isolation, use the Agent tool's isolation: "worktree" parameter — a different mechanism (see Related) |
| "create a branch" / "switch branches" | git switch or git checkout |
Once the user has explicitly asked for a worktree, it fits work that genuinely needs a second simultaneous checkout: a risky refactor that may be thrown away, a release-branch hotfix while feature work stays in the main tree, or two implementations compared side by side.
Tools
EnterWorktree
Creates a git worktree on a new branch. Use only when the user explicitly asks for a worktree.
Parameters:
name(optional) — Descriptive name for a new worktree (e.g.,fix-auth-bug,experiment-caching). Auto-generated if omitted.path(optional) — Path to an existing worktree to switch into instead of creating one. Mutually exclusive withname.
Behavior:
- Creates worktree in
.claude/worktrees/<name> - Branches from
origin/<default-branch>, NOT from local HEAD. The base ref is governed by theworktree.baseRefsetting, whose default isfresh; theheadvalue is what branches from local HEAD. It is a setting, not a call parameter — so uncommitted or unpushed local work is not carried into the worktree by default. - Switches the session's working directory to the worktree — this is session-wide state, not per-task state
- Full git history available — commits, pushes, etc. all work normally
ExitWorktree
Leave the worktree and return to the original working directory. Only operates on a worktree created by EnterWorktree in this session — otherwise it is a no-op, and it never touches manually created or previous-session worktrees. Call it when the user asks to exit, not proactively.
Parameters:
action(required) —"keep"or"remove"keep— Leave the worktree and branch on disk for laterremove— Delete the worktree directory and branch
discard_changes(optional, defaultfalse) — Only meaningful withremove.removerefuses when the worktree has uncommitted files or commits not on the original branch, and lists them; it proceeds only withdiscard_changes: true, which permanently discards that work. Treat the refusal as the safety net reporting unsaved work — confirm with the user before overriding it, never set it reflexively to clear the error.
Workflow Patterns
Every pattern below assumes the user has already explicitly asked to work in a worktree. None of them is a reason to reach for the tool on your own.
Experiment-then-Merge
EnterWorktreewith descriptive name (branches fromorigin/<default-branch>)- Implement the experimental approach
- Run tests to validate
- If successful: commit, exit with
keep, merge from main branch - If failed: commit or stash anything worth keeping, then exit with
remove. Ifremoverefuses, it is reporting unsaved work — inspect it rather than overriding withdiscard_changes
Two Features, Two Branches
Sequential, not concurrent — the single-instance rule means each worktree must be exited before the next is created. The payoff is two checkouts left on disk, not two things happening at once.
EnterWorktreefor feature A- Implement feature A, commit
ExitWorktreewithkeepEnterWorktreefor feature B- Implement feature B, commit
ExitWorktreewithkeep- Both branches exist independently — merge when ready
A/B Comparison
EnterWorktreefor implementation A, build it, commit,ExitWorktreewithkeepEnterWorktreefor implementation B, build it, commit,ExitWorktreewithkeep- Compare the two branches side by side — both checkouts remain on disk
- Merge the winner; delete the loser's branch with ordinary git commands
Bug investigation is not on this list. The tool's contract routes "fix this bug" and "diagnose this issue" to the normal git workflow — investigate in the main working directory and revert with
git checkout -- <file>.
Constraints
- Requires a git repository, or
WorktreeCreate/WorktreeRemovehooks in settings.json - Single-instance: cannot create a new worktree (
name) while already in a worktree session — exit first. Entering an existing worktree bypathis the exception - Session-scoped:
EnterWorktreemoves the whole session's working directory, so a worktree is never a per-task or per-batch isolation mechanism - Uncommitted changes or unmerged commits make
removerefuse unlessdiscard_changes: true - On session exit while in a worktree, user is prompted to keep or remove
When NOT to Use Worktrees
- No explicit instruction — if neither the user nor CLAUDE.md / memory said "worktree", stop here regardless of how isolated the work looks
- Bug fixes and feature work — the tool's contract routes these to the normal git workflow
- Simple branch switches — Use
git checkoutorgit switchinstead - Single-file experiments — Just edit and revert with
git checkout -- file - Non-git projects — Worktrees require git
Best Practices
- Name worktrees descriptively:
fix-auth-timeout,experiment-redis-cache,hotfix-v2.1 - Commit or push meaningful work before exiting —
removedeletes the local branch, anddiscard_changes: truepermanently destroys anything uncommitted - Use
keepwhen you plan to return or merge; useremovefor throwaway work — and read the refusal ifremovereports unsaved changes instead of forcing past it - Combine with
experiment-loopskill for metric-driven iteration, once a worktree has been explicitly requested
Related
Agenttool'sisolation: "worktree"parameter — the separate mechanism that gives one spawned agent a temporary git worktree, i.e. an isolated copy of the repo. This is what per-agent or per-task isolation uses; it is notEnterWorktreeand is not gated on the user saying "worktree"experiment-loopskill — Autonomous optimization patterns (can run inside worktrees)git-workflowskill — Branch management and commit conventions/checkpointcommand — Named save points (lighter weight than worktrees)