recover

/recover — Worktree & Branch Cleanup

Scan for orphaned worktrees, stale branches, and partial work left behind by crashed or abandoned Claude Code sessions. Read-only by default — reports findings and waits for approval before cleanup.

Invocation: deliberately model-invocable — scanning is read-only. Every cleanup action is gated on explicit user approval.

When to Use

• After a system crash or forced session termination
• When parallel session hooks warn about stale processes
• When you find commits on unknown branches
• Periodic hygiene (monthly or after heavy parallel work)

Instructions

0. Detect the default branch

Don't assume main. Resolve it once and use it everywhere below:

DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
DEFAULT=${DEFAULT:-$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p')}
DEFAULT=${DEFAULT:-main}   # no remote at all — fall back and note it in the report

1. List all worktrees

git worktree list --porcelain

Identify:

• Recently touched worktrees: files or .git metadata modified in the last hours — treat as possibly live. git worktree list cannot tell whether a session is actually running; without a lock/heartbeat file or process evidence, classify as unknown activity and never as orphaned.
• Candidate-orphaned worktrees: no recent modification and no activity signal — proceed to inspection, still gated on user approval before any cleanup
• Stale entries: Git tracks a worktree but the directory is gone

2. Inspect orphaned worktrees

For each orphaned worktree:

git -C <worktree-path> status --short
git -C <worktree-path> branch --show-current
git -C <worktree-path> log --oneline -3
git log "$DEFAULT"..<branch-name> --oneline

Classify each as:

• CLEAN: No unmerged commits, no uncommitted changes — safe to remove
• HAS COMMITS: Unmerged commits exist — needs merge decision
• HAS CHANGES: Uncommitted work — needs save decision
• BOTH: Unmerged commits AND uncommitted changes — needs careful handling