deadbranch CLI for stale-branch cleanup — dry-run preview, TUI or non-interactive delete, protects main/develop/WIP. Use when asked to clean up branches, prune branches, or remove stale branches.
deadbranch CLI for stale-branch cleanup — dry-run preview, TUI or non-interactive delete, protects main/develop/WIP. Use when asked to clean up branches, prune branches, or remove stale branches.
Survey stale git branches and clean them up safely. Always previews
before deleting; backup system means every deletion is recoverable.
When to Use This Skill
Use this skill when...
Use another approach when...
Asked to clean up, prune, or remove stale branches across a repo
Deleting a single known branch — git branch -d <name> is simpler
You want a survey of branch health (age, merge status, count) first
Doing routine gc / repo maintenance — use /git:maintain
You want recoverable deletion with a dry-run preview and backups
Pruning remote-tracking refs only — git remote prune origin
Parameters
Parse from $ARGUMENTS (all optional):
Flag
Default
Description
--days N
30
Age threshold — branches older than N days are stale
--local
off
Target local branches only
--remote
off
Target remote branches only
--force
off
Include unmerged branches (dangerous — ask for explicit confirmation)
--interactive
off
Open full-screen TUI for visual selection
--dry-run
on
Show what would be deleted without deleting (always on for the preview step)
--yes
off
Skip confirmation prompts (only use if user explicitly asks for automation)
--stats-only
off
Run stats + list only, skip the clean step entirely
When no flags are given, default to the survey-first workflow below.
Workflow
Step 1: Survey
Run in parallel:
deadbranch stats
deadbranch list
Report both outputs. The stats command shows total branch count, stale
count, and age distribution. The list shows each stale branch with its
age, merge status, last commit date, and author.
If --days N was provided, pass -d N to both commands.
If --local or --remote was provided, pass the flag to list.
If no stale branches are found, stop here and report the repo is clean.
If --stats-only was provided, stop here after reporting.
Step 1.5: Reclassify squash-merged branches
deadbranch classifies "merged" via commit ancestry (git branch --merged-style). On repos that squash-merge — the release-please /
conventional-commit default — the squash collapses a branch into a single new
commit on the base with a fresh SHA, so the branch's own commits are never
ancestors and it reads as unmerged. The "safe to delete" count is therefore
a lower bound on squash-merge repos (in one real cleanup, only 4 of 28
actually-merged branches were flagged safe).
After the survey, reclassify each branch deadbranch marked unmerged using
the signals below in this order of authority. A branch confirmed by any of
them is safe to delete; stop at the first one that answers.
A MERGED PR for the branch head — authoritative. GitHub records that the
squash landed the work at merge time, regardless of any later drift on the
base:
gh pr list --state all --head <branch> --json number,state,mergedAt
A MERGED state means the branch's work landed (read state / mergedAt,
never a merged field — see .claude/rules/gh-json-fields.md). --head <branch> is an exact per-branch query, so it is unaffected by gh pr list's 30-item default page — never build a branch→PR map from a repo-wide
gh pr list --limit N, which silently drops every PR outside the window and
misclassifies those branches as "no PR".
git cherry — patch-equivalence, which survives squash-merge and
cherry-pick even after the base drifts:
merge-tree — a positive-containment shortcut only (git ≥ 2.38). When
the merged tree equals the base's tree, the branch contributes nothing not
already present:
A match proves containment; a non-match proves nothing. Once the base
drifts over the same files, merging an already-landed branch back would
re-introduce its older versions, so the trees differ for work that fully
landed. Never use this as the primary signal: doing so is what made the
just -g branch-audit recipe's REVIEW bucket ~90% false on two real repos
(issue #2268). Treat a non-match as "review", never as "unmerged".
Report a "squash-merged (reclassified safe)" group alongside deadbranch's own
merged set so the user sees the true safe-to-delete count. Branches matching
none of the signals stay in the keep/review group — do not sweep them with
--force, which also deletes genuinely-unmerged work.
This reclassification is read-only — it never deletes. Deletion still flows
through the Step 2 dry-run and Step 3 confirmation below, with the
squash-merged branches included in the set the user approves.
Report the dry-run output. If nothing would be deleted (e.g. all stale
branches are unmerged and --force was not set), explain why and offer
to re-run with --force if the user wants to include unmerged branches.
Step 3: Confirm and clean
After the dry-run, ask the user what to do:
AskUserQuestion("Proceed with branch deletion?", options=[
"Yes — delete all shown branches",
"Interactive TUI — let me pick",
"No — survey only, skip deletion"
])
Yes: run deadbranch clean [options]
Interactive: run deadbranch clean --interactive [options]
(note: the TUI requires a real terminal — warn the user that this
opens a full-screen interface they must interact with directly via
! deadbranch clean --interactive)
No: print the summary and stop
If the user passed --interactive in $ARGUMENTS, skip the question
and go straight to TUI mode.
If --yes was explicitly passed, skip confirmation and delete directly.
Step 4: Report
After deletion, confirm with:
deadbranch backup list
Report how many branches were deleted and that their SHAs are backed
up (recoverable via deadbranch backup restore <branch>).
Safety Rules
Situation
Action
--force requested
Show extra warning: "This deletes unmerged branches. These are NOT recoverable from the remote." before dry-run
--remote requested
Note that remote deletion affects everyone on the team
Branch is WIP / draft
deadbranch skips these automatically; mention it in the report
