gh-sweep

gh-sweep

TUI for sweeping GitHub repositories: dead branches, unresolved review threads, protection drift, and slow workflows.

Installation

As a GitHub CLI extension:

Note: Requires a GitHub Release with precompiled binaries. For development, see local install instructions.

gh extension install kyleking/gh-sweep

With Homebrew, directly from the repository formula:

brew install --formula https://github.com/KyleKing/gh-sweep/raw/main/Formula/gh-sweep.rb

With Go:

go install github.com/KyleKing/gh-sweep/cmd/gh-sweep@latest

Or build from source:

go build -o gh-sweep ./cmd/gh-sweep

Usage

# Launch the full TUI (home menu with all views)
gh sweep

# Interactive branch management for one repo; --list prints a table instead
gh sweep branches --repo owner/repo
gh sweep branches --repo owner/repo --base develop --list

# Review unresolved PR review threads (GraphQL reviewThreads);
# without --pr, scans the newest open PRs (capped at 20)
gh sweep comments --repo owner/repo
gh sweep comments --repo owner/repo --pr 42 --list
gh sweep comments --repo owner/repo --author octocat --since 2026-01-01 --search TODO

# Compare branch protection across repos, optionally against a baseline
gh sweep protection --repos owner/repo1,owner/repo2 --baseline owner/repo1 --list

# Analyze GitHub Actions workflow performance
gh sweep gha-perf --repo owner/repo --list-workflows
gh sweep gha-perf --repo owner/repo -w ci.yml -l 50 --days 14
gh sweep gha-perf --repo owner/repo -w ci.yml --by-branch --base-branch main
gh sweep gha-perf --repo owner/repo -w ci.yml -j test --csv runs.csv

# Detect orphaned branches (merged PR, closed PR, or stale) across a namespace
gh sweep orphans --org my-org
gh sweep orphans --repos owner/repo1,owner/repo2 --stale-days 14 --list
gh sweep orphans --org my-org --cleanup --dry-run

# Audit repository watch status
gh sweep watching --unwatched
gh sweep watching --watch-all

The persistent --org and --repos flags work on every command and override the config file.

Configuration

An optional YAML config is read from the first of ./.gh-sweep.yaml, ~/.gh-sweep.yaml, or ~/.config/gh-sweep/config.yaml. Flags take precedence. See .gh-sweep.yaml.example for every key; the common ones:

# Default GitHub organization; bare repo names below are qualified with it
default_org: your-org

# Repositories to manage ("owner/repo" or "repo" with default_org)
repositories:
  - owner/repo1
  - repo2

# Baseline repository for protection/settings comparisons
baseline: owner/repo1

branches:
  default_branch: main
  protected_patterns: [main, master, develop, release/*]

orphans:
  stale_days_threshold: 7
  exclude_patterns: [main, master, develop, release/*, hotfix/*]

gha_perf:
  default_lookback_days: 30
  base_branch: main
  regression_threshold: 20.0

Keybindings

q or ctrl+c quits from any view; esc returns to the home menu. See UX.md for layout mockups.

Home menu

Branches and orphans

Tabbed views

Number keys switch tabs; j/k navigate within a tab.

Comments uses j/k plus r to toggle resolved threads; protection and webhooks are navigation only.

Features

• Branch management with ahead/behind counts and guarded batch delete (protected patterns are never deleted)
• Orphan detection across a whole org or user: branches whose PR merged, whose PR closed, or with no PR and no recent activity
• Unresolved review threads via the GraphQL reviewThreads API, filterable by PR, author, date, and text
• Branch protection drift table against a baseline repo
• GitHub Actions timing analysis with per-workflow, per-job, and per-branch stats, regression flagging, CSV export, and a JSON cache
• Read-only views for settings drift, webhook health, collaborator access, secrets inventory, and release age
• Watch-status audit with bulk watch/unwatch
• Catppuccin theme (Latte/Macchiato) auto-detected from the terminal background, CATPPUCCIN_THEME override

Development

mise install && hk install --mise
mise run ci

See CONTRIBUTING.md for the task table and release flow, DESIGN.md for architecture, and ROADMAP.md for planned milestones (including a demo GIF).

Alternatives

gh-dash is a personal PR and issue dashboard: a unified view of the PRs and issues assigned to you across repos, with a quick review workflow. Use it for daily triage of your own work, and gh-sweep for repository administration across many repos.

watchgha tails GitHub Actions runs live with streaming status updates. Use it while actively developing to watch CI in real time. gh-sweep's gha-perf command covers the historical side (duration trends, regressions, flaky heuristics).

gh-poi safely deletes local branches whose PRs have merged, from a single checkout. Use it for local single-repo hygiene. gh-sweep's branches and orphans commands work on remote branches across many repos without a checkout.

For automation categories gh-sweep deliberately avoids (dependency updates, settings as code, stale-issue bots, release automation), see docs/alternatives.md.

License

MIT