claude-code - 💡(How to fix) Fix [DOCS] EnterWorktree mid-session worktree switching not documented in worktrees guide

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/worktrees

Section/Topic

The worktrees guide — no section currently covers switching between existing Claude-managed worktrees mid-session.

Current Documentation

The worktrees guide describes creating and entering a single worktree:

You can also ask Claude to "work in a worktree" during a session, and it will create one with the EnterWorktree tool.

The tools reference mentions the path parameter:

Pass a path to switch into an existing worktree of the current repository instead of creating a new one.

The ExitWorktree tool description says it "Exits a worktree session and returns to the original directory."

Nowhere in the worktrees guide is it documented that EnterWorktree can be called from within an existing Claude-managed worktree to switch directly to another worktree, bypassing the need to call ExitWorktree first.

What's Wrong or Missing?

As of v2.1.157, EnterWorktree can switch between Claude-managed worktrees mid-session. A user working in worktree A can now call EnterWorktree with a path to switch directly into worktree B, without first exiting back to the main checkout.

The worktrees guide — the primary documentation page for worktree usage — does not cover this workflow at all. The guide frames worktree entry as a one-time action (enter from main, then exit back to main), when in practice users with multiple parallel worktrees benefit from direct switching.

Suggested Improvement

Add a section to the worktrees guide documenting the mid-session switching workflow. Suggested content:

Add after "Start Claude in a worktree" (after line 35 in current mirror):

### Switch between worktrees mid-session

If you have multiple worktrees open in parallel, you can switch from one to another without
returning to the main checkout first. Ask Claude to switch into another worktree by name or path:

"Switch to the worktree at .claude/worktrees/bugfix-123"

Claude calls `EnterWorktree` with a `path` to switch directly into the target worktree.
This works from within any existing Claude-managed worktree, from the main checkout,
or from a manually created worktree.

Also update the ExitWorktree tool reference to clarify that it returns to the directory from which the session was originally launched, not necessarily the previous worktree.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected (1 requires workflow documentation, 1 could benefit from clarification)

v2.1.157 changelog entry: "EnterWorktree can now switch between Claude-managed worktrees mid-session"