Clean Branches Auto

Automatically identify and delete local git branches that have been merged, are stale, or no longer have a remote counterpart, keeping your repository tidy.

When to Use This Command

Run this command when...

• Your local repository has accumulated dozens of feature branches already merged upstream
• You want to prune branches whose remote tracking branch has been deleted
• You need a clean git branch listing to find your active work quickly

Avoid this command when...

• You have unmerged work on local branches that you have not pushed anywhere
• You are working with a shared local repository where other users rely on those branches

Quick Start

Copy
# .claude/commands/clean-branches-auto.md
---
allowed-tools: ["Bash"]
---
Fetch remote state, identify merged and orphaned local branches,
list them for confirmation, then delete. Never deletes main/master.

Example usage:

/clean-branches-auto

Example output:

Fetching remote state... done
Analyzing 23 local branches...

Branches to delete:
  [MERGED]   feature/login-redesign
  [MERGED]   fix/header-alignment
  [ORPHAN]   feature/old-experiment (remote deleted)
  [STALE]    spike/perf-test (no commits in 90 days)

Protected: main, develop (never deleted)
Deleting 4 branches... done
Remaining: 19 branches

Core Concepts

Concept	Description
Merged detection	Checks if a branch is fully merged into main or master
Orphan detection	Identifies branches whose upstream remote tracking ref is gone
Stale detection	Flags branches with no new commits in N days
Protected branches	Never deletes main, master, develop, or release branches

git fetch --prune --> List Local Branches
                           |
              +------------+------------+
              |            |            |
          Merged?      Orphaned?     Stale?
              |            |            |
              +--- Candidates List -----+
                           |
                    Filter Protected
                           |
                     Delete Branches

Configuration

Option	Default	Description
protected	main,master,develop	Branches that are never deleted
stale-days	90	Days since last commit to consider a branch stale
dry-run	false	List candidates without actually deleting them
include-remote	false	Also delete matching remote branches
force	false	Force-delete even if branch is not fully merged

Best Practices

1. Run dry-run first -- always preview what will be deleted before committing to the cleanup.
2. Keep protected list updated -- add release and hotfix branch patterns to the protected list.
3. Run monthly -- prevents branch buildup from becoming overwhelming over time.
4. Never force-delete without checking -- unmerged branches may contain work that is not pushed anywhere else.
5. Fetch before cleaning -- always fetch remote state first so orphan detection is accurate.

Common Issues

1. Important branch deleted -- use git reflog to find the branch tip commit and recreate it with git branch <name> <sha>.
2. Branch not detected as merged -- squash-merged PRs do not show as merged in git. Use a squash-merge detection flag if your workflow uses squash merges.
3. Permission denied on remote delete -- you need push access to the remote to delete remote branches. Check your permissions.