claude-code - 💡(How to fix) Fix [DOCS] Worktrees page doesn't document that Claude unlocks worktrees when the agent finishes so `git worktree remove`/`prune` can clean them up

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Clean up worktrees" section and "Manage worktrees manually" section

Current Documentation

The "Clean up worktrees" section on the worktrees page covers cleanup behavior:

When you exit a worktree session, cleanup depends on whether you made changes:

• No uncommitted changes, no untracked files, and no new commits: the worktree and its branch are removed automatically.
• Uncommitted changes, untracked files, or new commits exist: Claude prompts you to keep or remove the worktree.
• Non-interactive runs: worktrees created with --worktree alongside -p are not cleaned up automatically since there is no exit prompt. Remove them with git worktree remove

The "Manage worktrees manually" section shows:

Remove one when you're done with it:

git worktree remove ../project-feature-a

What's Wrong or Missing?

The docs tell users to run git worktree remove to clean up leftover worktrees, but they don't mention that Claude leaves worktrees unlocked when the agent finishes (starting in v2.1.157). This is critical context because git worktree remove and git worktree prune refuse to touch a locked worktree. Without documenting this unlock behavior, the cleanup instructions appear to promise something that would fail if the user tried it before v2.1.157 — and users on older versions who read the current docs won't understand why git worktree remove fails on Claude-managed worktrees.

Specifically, the "Clean up worktrees" section should explain that:

• Worktrees managed by Claude are unlocked when the agent finishes, enabling manual cleanup with git worktree remove or git worktree prune
• Earlier versions may have left worktrees locked, which would prevent these commands from working

Suggested Improvement

Add a note to the "Clean up worktrees" section explaining the unlock behavior. For example, after the "Non-interactive runs" bullet point:

> **Note:** Worktrees managed by Claude are left unlocked when the agent finishes (v2.1.157+), so `git worktree remove` and `git worktree prune` can clean them up. In earlier versions, Claude locked worktrees during operation, which blocked manual cleanup.

This could also be added as context in the "Manage worktrees manually" section near the git worktree remove command.

Impact

Medium - Makes feature difficult to understand

Additional Context

This behavior change was introduced in Claude Code v2.1.157, per the changelog entry: "Worktrees managed by Claude are now left unlocked when the agent finishes, so git worktree remove/prune can clean them up."

Affected Pages:

Total scope: 1 page affected