[DOCS] Worktree cleanup docs missing automatic recovery of stale worktrees from interrupted parallel runs

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/common-workflows

Section/Topic

"Worktree cleanup" subsection under "Run parallel Claude Code sessions with Git worktrees"

Current Documentation

The "Worktree cleanup" section describes the normal (graceful) exit cleanup path only:

"When you exit a worktree session, Claude handles cleanup based on whether you made changes: - No changes: the worktree and its branch are removed automatically - Changes or commits exist: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding all uncommitted changes and commits" "To clean up worktrees outside of a Claude session, use manual worktree management."

There is no mention of what happens when a parallel run is interrupted abnormally (crash, kill signal, Ctrl+C during a multi-agent run).

What's Wrong or Missing?

Worktrees created during a parallel run (e.g., when Claude spawns multiple subagents with isolation: worktree) can be orphaned if the run is interrupted before the cleanup phase executes. Prior to v2.1.76, these stale worktrees accumulated silently and required manual removal. Version 2.1.76 added automatic detection and cleanup:

"Improved stale worktree cleanup — worktrees left behind after an interrupted parallel run are now automatically cleaned up"

The current documentation only describes the happy-path cleanup scenario. Users who experience an interrupted parallel run have no documentation explaining:

• That orphaned worktrees are automatically detected and cleaned up on the next session start
• Whether any data from the interrupted run is preserved or discarded
• How to manually clean up if automatic cleanup does not run (the manual worktree management section covers this partially, but without the context of stale/orphaned worktrees)

Suggested Improvement

Add a "Stale worktree recovery" paragraph to the "Worktree cleanup" section in common-workflows.md, after the existing cleanup bullets:

Stale worktree recovery If a parallel run is interrupted (for example, by Ctrl+C, a crash, or a lost connection), worktrees created for that run may be left behind. Claude Code automatically detects and removes these stale worktrees when it starts a new session. No manual intervention is needed. If you prefer to clean them up immediately, use git worktree list to see all worktrees and git worktree remove <path> to remove them manually. Claude Code worktrees are created at .claude/worktrees/.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/common-workflows | "Worktree cleanup" subsection — covers only graceful exit, not stale/orphaned recovery |

Total scope: 1 page affected

Source: Changelog v2.1.76

Improved stale worktree cleanup — worktrees left behind after an interrupted parallel run are now automatically cleaned up