claude-code - 💡(How to fix) Fix [DOCS] Worktree docs do not clarify `--worktree` and `--tmux` behavior when invoked from inside a linked git worktree

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

"Start Claude in a worktree" section — the description of --worktree flag behavior does not address running from inside an existing linked worktree.

Also: --tmux flag entry in the CLI reference.

Current Documentation

The worktrees page says:

Pass --worktree or -w to create an isolated worktree and start Claude in it. By default, the worktree is created under .claude/worktrees/<value>/ at your repository root, on a new branch named worktree-<value>

The CLI reference says:

--tmux | Create a tmux session for the worktree. Requires --worktree.

Neither page addresses what happens when --worktree (with or without --tmux) is run from inside an existing linked git worktree directory.

What's Wrong or Missing?

The docs describe --worktree exclusively from the perspective of the canonical/main checkout. They do not describe:

1. Whether --worktree is supported from inside a linked worktree
2. Where the new worktree is created relative to the repository root when invoked from inside a linked worktree
3. Whether --tmux behaves the same way when combined with --worktree from inside a linked worktree

As of v2.1.157, a bug was fixed where --worktree and --worktree --tmux incorrectly resolved to the canonical repository root instead of the current linked worktree. This fix confirms the intended behavior (staying in the linked worktree context), but the docs have not been updated to reflect it.

Suggested Improvement

Add a paragraph after the existing --worktree description clarifying the behavior from inside a linked worktree:

After:

Pass --worktree or -w to create an isolated worktree and start Claude in it. By default, the worktree is created under .claude/worktrees/<value>/ at your repository root, on a new branch named worktree-<value>.

When run from inside a linked git worktree, --worktree resolves the repository root from the current worktree's git metadata and creates the new worktree at that root, not at the canonical checkout. This means you can cd into any git worktree and run claude -w new-task to create another isolated worktree from there.

Also add a note to the --tmux CLI reference entry clarifying that it inherits the same worktree-context resolution behavior as --worktree.

Impact

Low - Minor confusion or inconvenience

Additional Context

Affected Pages:

Total scope: 2 pages affected

Version context: The bug where --worktree and --worktree --tmux returned to the canonical repo root instead of the current linked worktree was fixed in v2.1.157. The docs should reflect the current (fixed) behavior.