Worktree Workflow

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:

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 with name.

Behavior:

• Creates worktree in .claude/worktrees/<name>
• Branches from origin/<default-branch>, NOT from local HEAD. The base ref is governed by the worktree.baseRef setting, whose default is fresh; the head value 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 later
  • remove — Delete the worktree directory and branch
• discard_changes (optional, default false) — Only meaningful with remove. remove refuses when the worktree has uncommitted files or commits not on the original branch, and lists them; it proceeds only with discard_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

1. EnterWorktree with descriptive name (branches from origin/<default-branch>)
2. Implement the experimental approach
3. Run tests to validate
4. If successful: commit, exit with keep, merge from main branch
5. If failed: commit or stash anything worth keeping, then exit with remove. If remove refuses, it is reporting unsaved work — inspect it rather than overriding with discard_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.

1. EnterWorktree for feature A
2. Implement feature A, commit
3. ExitWorktree with keep
4. EnterWorktree for feature B
5. Implement feature B, commit
6. ExitWorktree with keep
7. Both branches exist independently — merge when ready

A/B Comparison

1. EnterWorktree for implementation A, build it, commit, ExitWorktree with keep
2. EnterWorktree for implementation B, build it, commit, ExitWorktree with keep
3. Compare the two branches side by side — both checkouts remain on disk
4. 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 / WorktreeRemove hooks in settings.json
• Single-instance: cannot create a new worktree (name) while already in a worktree session — exit first. Entering an existing worktree by path is the exception
• Session-scoped: EnterWorktree moves 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 remove refuse unless discard_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 checkout or git switch instead
• 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 — remove deletes the local branch, and discard_changes: true permanently destroys anything uncommitted
• Use keep when you plan to return or merge; use remove for throwaway work — and read the refusal if remove reports unsaved changes instead of forcing past it
• Combine with experiment-loop skill for metric-driven iteration, once a worktree has been explicitly requested

Related

• Agent tool's isolation: "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 not EnterWorktree and is not gated on the user saying "worktree"
• experiment-loop skill — Autonomous optimization patterns (can run inside worktrees)
• git-workflow skill — Branch management and commit conventions
• /checkpoint command — Named save points (lighter weight than worktrees)