repo-cleanup

Deletes merged git worktrees, local branches, and remote branches after pull request merges.

Updated Aug 8, 2026
One-click install
npx skills add https://github.com/headwater-ai/headwater --skill repo-cleanup-headwater-ai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: repo-cleanup
Source: https://github.com/headwater-ai/headwater/tree/main/.claude/skills/repo-cleanup
Command: npx skills add https://github.com/headwater-ai/headwater --skill repo-cleanup-headwater-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Finished work leaves behind stale worktrees, local branches, and remote branches that accumulate until the branch list no longer reflects open work. Standard ancestry checks like git branch --merged fail on squash-merged and rebased repositories, so cleanup either deletes nothing or risks deleting unmerged work. ## Core Features & Use Cases - Content-based merge detection: Decides whether a branch is merged by checking pull request state and commit content against origin/main, not by ancestry, so squash and rebase merges are handled correctly. - Safe ordered deletion: Removes worktrees first, then local branches, then remote branches, recording branch tips before deletion and refusing anything the content check did not clear. - Survivor reporting: Produces a report naming every branch and worktree left in place with the reason: dirty, locked, in use, unmerged, or a closed-but-unmerged pull request. - Use Case: After merging several pull requests in a squash-merge repository, run a sweep to retire the leftover worktrees and branches, and get a report of the two branches that still hold unmerged commits. ## Quick Start Ask the assistant to clean up merged branches and worktrees in this repository and report anything that is not safe to delete.

Frequently Asked Questions about repo-cleanup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I delete merged git branches after a squash merge?

Check the pull request state with `gh pr list --head <branch> --state all` and confirm the local tip is an ancestor of the merged head commit. Squash merges rewrite history, so `git branch --merged` reports these branches as unmerged even though their content landed in main.

How do I remove a git worktree and its branch safely?

Remove the worktree first with `git worktree remove <path>`, then delete the branch, then delete the remote branch. A branch checked out in a worktree cannot be deleted, and removing the directory by hand leaves a stale administrative entry that `git worktree prune` must clear.

Why does git branch -d refuse to delete my merged branch?

`git branch -d` measures the branch against its upstream or HEAD, not against origin/main, so it refuses squash-merged branches and branches merged while another branch is checked out. Its refusal carries no information about whether the content actually merged.

What does a gone upstream branch mean in git?

A `gone` upstream means the remote branch was deleted, which has three causes: a merged pull request with delete-on-merge enabled, a closed unmerged pull request, or a rewritten history. Check pull request state and commit content to tell them apart before deleting the local branch.

When should I not delete a branch during repository cleanup?

Never delete branches with open pull requests, unmerged commits, locked worktrees, worktrees with uncommitted changes, or the worktree the current session runs in. main and tags are never candidates, and unmerged branches should be reported rather than force-deleted.