Stale worktrees are never cleaned up

[atrimble-synmax]

Problem

Claude Code creates git worktrees under ~/.claude-worktrees/ for parallel task execution but has no mechanism to clean them up if a session ends without proper cleanup (crash, interruption, or bug in teardown). There is also no garbage collection on subsequent session starts — each session is completely unaware of what previous sessions left behind.

This leaves behind:

1. Full repo copies on disk (wasting space)
2. Git branches that cannot be deleted even with git branch -D because git refuses to delete a branch checked out in any worktree
3. Worktree refs in .git/worktrees/ that persist indefinitely

The only way a user discovers these is by stumbling into the cannot delete branch error, at which point they have to manually git worktree remove or rm -rf the directory, then git worktree prune to clean up refs.

Reproduction

1. Use Claude Code on a project where it creates a worktree (parallel task execution)
2. End the session (or have it crash/interrupt)
3. Observe that ~/.claude-worktrees/<project>/<worktree-name> persists
4. Try to delete the branch: git branch -D <worktree-name> → fails with error: cannot delete branch used by worktree

Expected behavior

• Claude Code should clean up worktrees on session exit
• On session start, Claude Code should scan for and prune stale worktrees from previous sessions
• At minimum, a claude --cleanup command or similar should exist

Environment

• macOS (Darwin 25.2.0)
• Claude Code (CLI)
• Found a stale worktree from January 15, 2026 that was never cleaned up across dozens of subsequent sessions

[karan-dhir]

Same issue here. Had 15 orphaned agent worktrees from a single session where sub-agents were launched with isolation: "worktree". All nested under a parent session worktree, none cleaned up on exit. Had to manually git worktree remove --force each one + delete the branches + git worktree prune.

+1 for either automatic cleanup on session exit or a claude --cleanup command.

[asportnoy]

Same issue. Once or twice I did get a prompt when exiting Claude for "Do you want to delete this worktree?" but for some reason it's not showing up the vast majority of the time. Not sure why.

[Celtiore]

Reproduction with Agent tool + isolation: "worktree"

Same issue here — using the Agent tool with isolation: "worktree" to spawn parallel Dev agents during a planning/execution workflow (VBW plugin). A single session created 7 nested worktrees under .claude/worktrees/, none cleaned up on agent completion.

What happened

• Spawned 6 Dev agents (2 per phase, 3 phases) with isolation: "worktree" during one session
• After each agent completed and its branch was merged back to main, the worktree + branch persisted
• One agent even created a nested worktree inside another agent's worktree (.claude/worktrees/agent-a21cfb32/.claude/worktrees/agent-af7f3668)
• Total: 12 orphan worktree-agent-* branches, 7 worktree directories with uncommitted changes

Screenshot (VS Code Source Control showing all orphan worktrees)

TODO: Screenshot to be added via drag-and-drop (GitHub API does not support image upload)

Manual cleanup required

# Remove all agent worktrees
for wt in $(git worktree list --porcelain | grep "^worktree " | grep ".claude/worktrees" | sed 's/^worktree //'); do
  git worktree remove --force "$wt"
done
git worktree prune
# Delete orphan branches
git branch | grep worktree-agent | xargs git branch -D
rm -rf .claude/worktrees/

Suggestion

Since sub-agents spawned via the Agent tool with isolation: "worktree" are ephemeral by design (their commits get merged back to the parent), cleanup should be automatic when the agent returns its result. At minimum, a SessionStart garbage collection pass would catch leftovers from crashed sessions.

Environment: macOS Darwin 25.3.0, Claude Code CLI, Claude Opus 4.6