Git Cleanup

A Claude Code slash command for safely cleaning up accumulated git worktrees and local branches.

What It Does

Analyzes your local git repository and sorts branches and worktrees into:

• Delete candidates: merged into the default branch (-d), or squash-merged or superseded with a named PR or commit as evidence (-D)
• Needs review: work that could not be located in the default branch, including [gone] remotes and any candidate a skeptic managed to refute
• Keep: unpushed commits, untracked local work, or level with a live remote
• Unanalyzed: branches no verdict came back for, listed explicitly so a partial run never reads as a complete one

The command is gated: it requires explicit user confirmation before any deletion.

How It Works

Analysis runs as a dynamic workflow — a JavaScript orchestration script that coordinates subagents:

1. Survey — one agent inventories branches, worktrees, tracking state, and recent merge history.
2. Triage — the script decides, in plain JavaScript, everything git can already prove: merged branches, branches with unpushed commits, branches level with a live remote. No agent is spawned for a question git branch --merged already answers.
3. Investigate — batched agents hunt for merge evidence on the branches that remain ambiguous, mostly [gone] remotes and groups of similarly-named branches. Related branches go to one agent so supersession is visible.
4. Refute — every delete candidate goes to a skeptic whose job is to find a commit that is not in the default branch. A refuted candidate is downgraded to "needs review", never deleted.

Typical runs are small: a repo with a dozen branches spawns about three agents, because the triage in step 2 decides most of them without spawning anything. Eleven is the ceiling, not the norm — one survey, at most five investigators, at most five skeptics — and past five batches the batches grow rather than the agent count, so the number stops rising even as the repository gets messier. Tokens still scale with the number of ambiguous branches; it is the coordination cost that is capped, not the reading.

The workflow is strictly read-only. Both confirmation gates and every git branch -d/-D and git worktree remove run in the main session, because subagents have no way to ask the user anything.

When to Use

Invoke with /git-cleanup when you have accumulated many local branches and worktrees that need cleanup.

Important: the command sets disable-model-invocation: true, so Claude cannot invoke it on its own — it runs only when you type it. That flag is what closes autonomous invocation; the description in the frontmatter is matchable text and would otherwise let a cleanup-shaped request trigger a plugin whose job is git branch -D.

Safety Features

• Two confirmation gates (analysis review, then deletion confirmation), both in the main session
• Safe delete (git branch -d) for branches git itself reports as merged; force delete (git branch -D) only for squash-merged and superseded branches, where git compares shas and cannot see that a squash carried the work across
• Every squash-merged or superseded candidate must survive a skeptic tasked with finding a commit the claim cannot account for — tested against whatever the claim named, the default branch for a PR or commit and the superseding branch for a supersession. Refuted, unverified, missing a verdict, and lost-to-a-failed-agent all fall back to needs-review. SAFE_TO_DELETE is the one category that skips this. It does not rest on git branch -d catching a mistake at execution time: -d accepts a branch merged into HEAD or into its own upstream, neither of which is "merged into the default branch". Instead each entry names its tip commit in its evidence, for a human to check at gate 1, and ships a verifyWith precondition — git merge-base --is-ancestor 'refs/heads/ ' ' ' — which the main session runs immediately before the delete and skips the delete on failure. The precondition names the branch rather than the reported sha, so it cannot pass on a stale or transposed commit while the branch itself was never merged. The category is still pinned to -d and never -D