home / skills / jmerta / codex-skills / branch-cleaner

branch-cleaner skill

This skill helps you safely prune stale git branches locally and remotely with reversible steps and explicit delete commands.

npx playbooks add skill jmerta/codex-skills --skill branch-cleaner

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: branch-cleaner
description: Identify and clean up stale git branches locally and on remotes with safe, reversible steps. Use when asked to prune, list, or delete merged/old branches or audit branch hygiene.
---
# Branch cleaner

## Goal
Safely identify stale branches and provide explicit delete/prune commands.

## Inputs to confirm (ask if missing)
- Default branch (main/master/develop).
- Remote name (origin) and whether remote deletion is desired.
- Safety rules: keep patterns (release/*, hotfix/*), minimum age, merged-only.

## Workflow
1) Sync and inspect
   - Run `git fetch --prune`.
   - Check `git status` and note uncommitted changes.
2) Build candidate lists
   - Local merged into default: `git branch --merged <base>`
   - Local not merged (list only): `git branch --no-merged <base>`
   - Remote merged: `git branch -r --merged <base>`
   - Stale by date: `git for-each-ref --sort=committerdate refs/heads --format="%(committerdate:short) %(refname:short)"`
3) Exclude protected branches
   - Always keep `<base>`, current branch, and user-provided patterns.
4) Confirm with user
   - Present candidates grouped by local vs remote.
5) Provide delete commands
   - Delete branches approved for deletion by the user
   - 

## Optional GitHub CLI checks
- `gh pr list --state merged --base <base>` to correlate merged branches.
- `gh pr view <branch>` to verify status if needed.

## Deliverables
- Candidate lists and rationale.
- Warnings for unmerged or recently updated branches.
- Don't remove remote branches unless explicitly approved.

Overview

This skill identifies stale Git branches and helps you safely prune them locally and on remotes with reversible, explicit commands. It groups candidates, explains why each branch is flagged, and only performs destructive actions after confirmation. Use it to audit branch hygiene and generate safe delete/prune commands rather than forcing automatic removals.

How this skill works

The skill first syncs with remotes (git fetch --prune) and inspects local status for uncommitted changes. It builds candidate lists: local merged, local unmerged, remote merged, and branches stale by last commit date. Protected branches (default branch, current branch, and user-specified patterns) are excluded. It presents grouped candidates, flags risks (unmerged or recent activity), and outputs explicit git and gh commands for approved deletions or pruning.

When to use it

Pruning branches after a release or sprint to reduce clutter
Auditing repository branch hygiene before cleanup work
Preparing a pull-request-based cleanup using gh to verify merged status
Generating safe, reviewable delete commands for local and remote branches
Enforcing retention rules (age, merged-only, keep patterns) across a repo

Best practices

Confirm the default base branch (main/master/develop) and current branch before actions
Specify keep patterns (e.g., release/*, hotfix/*) to protect important branches
Prefer listing and reviewing candidates first; only delete after explicit approval
Avoid remote deletions unless the user explicitly approves and understands consequences
Use gh CLI checks to correlate merged PRs when available for extra safety

Example use cases

List branches merged into main and produce local delete commands for approved ones
Detect branches with no recent commits older than X days and recommend pruning
Show remote branches merged into base and prepare git push --delete commands after approval
Audit branches that are not merged so you can decide whether to rebase, archive, or delete
Generate a step-by-step cleanup plan that includes fetching, status checks, candidate grouping, and delete commands

FAQ

Will this skill delete branches automatically?

No. It only generates and shows explicit delete/prune commands and performs deletions only after you confirm each action.

How does it decide which branches are stale?

It uses merged status, committer date sorting, and user-provided minimum age; protected patterns and the default/current branch are always excluded.

Can it remove remote branches?

Yes, but only if you explicitly approve remote deletion. It will warn about consequences and provide git push --delete or gh commands for review.