worktree-cleanup

Worktree Cleanup

Run this workflow only when the user explicitly invokes $worktree-cleanup. It performs repository-wide discovery and can remove worktrees. Always audit first, present the exact candidates, and apply only the approval tokens the user selects.

Requirements

Require Git, Python 3.10+, GitHub CLI, and an authenticated gh session with read access to the repository's pull requests. Run from a repository checkout or pass --repo <path>.

Audit

1. Check the current branch, git status --short, and git worktree list. Preserve concurrent and unrelated work.

2. Create a new temporary report path outside the repository and run the helper in dry-run mode:

   python3 <skill-dir>/scripts/cleanup_worktrees.py \
     --repo <repo-path> \
     --dry-run \
     --json \
     --write-approval-report <temporary-report.json>
   

3. Review every candidate and skip reason. A candidate is eligible only when all of these hold:

   • Git status is known and clean, including untracked files.
   • The worktree is neither locked nor marked prunable.
   • It is not the primary checkout or the checkout selected by --repo.
   • Its exact HEAD is contained in the remote head of a merged or closed GitHub pull request; or no pull request exists, the worktree is at least 24 hours old by default, and its HEAD is either the tip of a GitHub remote branch or contained in the remote default branch.

4. Review ignored.discarded_sample and ignored.discarded_count for every candidate. These count ignored path roots, not files or bytes; one listed directory may contain substantial data. .local is backed up; all other ignored files are deliberately discarded if that candidate is approved.

5. Tell the user the exact paths, whether each path is managed or external, remote durability proof, ignored data impact, backup base directory, and all retained paths with their reasons. Ask once whether to remove all listed candidates or a named subset; do not make the user copy or re-approve token strings. Worktrees outside .worktrees/ follow the same eligibility rules.