Stale Branch Cleaner

Audits the branches of a git repository, ranks them by how likely they are to be dead, presents the candidates for deletion, and deletes only what the user explicitly confirms — locally, on the remote, or both.

Deletion is destructive and, on a remote, effectively public. This skill NEVER deletes anything before an explicit confirmation, and never widens the scope it was given.

When to use

"clean up my branches", "which branches can I delete", "prune stale branches"
"my repo has 60 branches and I don't know which are dead"
Before a repo handover, an audit, or a release cleanup.

Do not use it to delete a branch the user already named — that is a one-line git command, not an audit.

Inputs to establish first

Ask only for what you cannot detect. Detect the rest.

Repository path — default: the current working directory. Refuse to continue if it is not a git work tree.
Staleness threshold — default: 90 days since the last commit. State the default; let the user override.
Protected branches — never proposed for deletion under any circumstance: main, master, develop, dev, staging, production, prod, release, release/*, HEAD, the current branch, and the remote's default branch. Add anything the user names.

Steps

Refresh the view of the remote (read-only, safe): git fetch --all --prune --quiet --prune only cleans up local tracking refs for branches already deleted on the remote; it deletes no branches. Say so if the user asks.
Collect the facts in one pass, so every judgement rests on real data:
```
git for-each-ref --sort=committerdate \
  --format='%(refname:short)|%(committerdate:iso8601)|%(authorname)|%(upstream:track)' \
  refs/heads refs/remotes
```
For each branch also determine:
- days since last commit — from the date above;
- merged or not: git branch --merged <default-branch> (local) and git branch -r --merged origin/<default-branch> (remote);
- unmerged commits that would be lost: git log --oneline <default-branch>..<branch> | wc -l;
- whether a local branch still has a live remote counterpart, and vice versa.

Classify each non-protected branch:

Class	Meaning	Default proposal
`MERGED`	fully merged into the default branch	propose deletion at any age
`STALE`	older than the threshold, has unmerged commits	propose, flagged with the commit count
`GONE`	local branch whose upstream is gone (`[gone]`)	propose local deletion
`ACTIVE`	newer than the threshold	keep, do not list among candidates

Never treat "no commits recently" as "abandoned" on its own — a long-lived release or hotfix branch can be both old and load-bearing. Anything with unmerged work is flagged, not quietly bundled in.

Present the list and stop. Group by class, most confident deletions first. For each branch show: name, age, last author, merged status, unmerged commit count, and where it exists (local / origin / both). Show the totals. Then state explicitly that nothing has been deleted yet.
Ask for the scope — this is a separate question from which branches, and it has no default:
- local only — safe, reversible, affects nobody else;
- origin only — affects everyone who uses the repo;
- both.
Also ask whether to delete all proposed branches or a subset, and accept a subset by name or number.
Confirm before acting. Restate the exact branch names and the exact scope, then wait for a clear yes. Treat silence, "ok whatever", or an ambiguous reply as "no". If the scope includes origin, say plainly that remote deletion affects other people and that recovery requires someone to still hold the commit.
Delete only what was confirmed, one branch at a time, reporting each result:
- local, merged: git branch -d <branch>
- local, unmerged (only if the user confirmed knowing the commit count): git branch -D <branch>
- remote: git push origin --delete <branch>
Before deleting anything unmerged, print its tip SHA so it can be recovered with git checkout -b <name> <sha>. Recovery is possible while the commit is still in the reflog or held by another clone.
Report: deleted, skipped, failed (with the error). If any deletion failed — branch protection rules, no push rights, an open PR — say which and why, and do not retry with a more forceful command.

Rules

Never delete without an explicit confirmation naming the scope. No exceptions, including when the user says "just clean it up".
Never git push --delete a protected branch, even if asked; say why and stop.
Never force-delete (-D) a branch with unmerged commits unless the user confirmed after seeing the commit count.
Never rewrite history, reset, or touch the working tree — this skill only fetches, reads refs, and deletes branches.
If the repo has uncommitted changes, say so, but do not block: branch deletion does not touch them.
If a branch has an open pull request, mention it and exclude it from the default proposal.

Output format

Repository: <path>   Default branch: <name>   Threshold: <N> days
Scanned: <N> local, <N> remote   Protected: <list>

MERGED — safe to delete (<n>)
  feature/login-form      142d   J. Novak    merged      local+origin
  ...

STALE — unmerged work (<n>)
  spike/graphql           210d   M. Dvorak   3 commits ahead   origin only
  ...

GONE — upstream deleted (<n>)
  fix/typo                 88d   J. Novak    [gone]      local only

KEEPING: <n> active branches

Nothing deleted yet. Delete which branches, and where — local only, origin only, or both?

After deletion:

Deleted (local): <list>
Deleted (origin): <list>
Skipped: <list with reasons>
Failed: <list with errors>
Recovery: <branch> tip was <sha> — git checkout -b <branch> <sha>

License

MIT

stale-branch-cleaner