Cleanup Complete Branches

Cleanup Complete Branches

Remove completed worktrees, local branches, and GitHub branches without touching active work.

Workflow

1. Start With A Preview

Always run the bundled script in dry-run mode first:

python3 .agents/skills/cleanup-complete-branches/scripts/cleanup_complete_branches.py

Dry-run mode fetches and prunes remotes, then reports what would be removed. It must not delete anything.

Review the output before applying changes. Treat these as blockers:

• A worktree is dirty.
• A branch has no merged GitHub PR and is not merged into origin/main.
• The branch name is protected.
• GitHub CLI authentication is missing and completion cannot be proven from git history alone.

2. Apply The Cleanup

If the dry run only lists completed branches and clean worktrees, apply it:

python3 .agents/skills/cleanup-complete-branches/scripts/cleanup_complete_branches.py --apply

The script removes clean completed worktrees first, then deletes matching local branches, then deletes matching origin branches on GitHub.

3. Optional Cases

Only remove closed-but-unmerged PR branches when the user explicitly asks for branches from abandoned or closed PRs to be removed:

python3 .agents/skills/cleanup-complete-branches/scripts/cleanup_complete_branches.py --apply --include-closed-unmerged

Use --force-worktrees only when the user explicitly accepts losing uncommitted files inside completed worktrees:

python3 .agents/skills/cleanup-complete-branches/scripts/cleanup_complete_branches.py --apply --force-worktrees

Safety Rules

• Never delete main, master, develop, dev, release, staging, or production.
• Never delete the currently checked-out branch.
• Never delete a dirty worktree unless the user explicitly requested force.
• Prefer GitHub PR status for squashed PRs, because git ancestry may not show squashed branches as merged.
• If a branch is ambiguous, report it and leave it alone.
• Do not close GitHub issues or PRs as part of cleanup.

Reporting

Summarize:

• Worktrees removed or skipped.
• Local branches removed or skipped.
• GitHub branches removed or skipped.
• Any branches that need the user's decision.