| name | git-branch |
| description | Manage, scan, and prune branches across multiple local Git repositories using git-branch-dashboard |
git-branch skill
When to use
Use this skill when the user needs to:
- Track branch age and staleness across one or more Git repositories
- View open PR/MR status overlaid on branch data
- Delete stale branches safely with a two-step confirmation
- Run scheduled or manual repository scans
- Configure staleness thresholds and API tokens
Prerequisites
- Node.js 20+
- pnpm
- Git 2.20+ in PATH
- Optional: GitHub personal access token (scope:
read:repo) for PR status
- Optional: GitLab personal access token (scope:
read_api) for MR status
Installation
npm install -g git-branch-dashboard
Or run from source:
git clone https://github.com/your-org/git-branch-dashboard
cd git-branch-dashboard
pnpm install
pnpm build
pnpm link --global
Quick Start
# Start the dashboard server (opens http://127.0.0.1:7654)
git-branch-dash start
# Add a local repository
git-branch-dash repo add /path/to/my-repo
# Set GitHub token for PR status
git-branch-dash config set github-token ghp_...
# Trigger a manual scan
git-branch-dash scan
Usage Patterns
Tracking a monorepo workspace
Add each sub-package as a separate repository path if they are independent Git clones. If they share a single .git directory, add the root once.
git-branch-dash repo add /workspace/packages/api
git-branch-dash repo add /workspace/packages/web
git-branch-dash repo add /workspace/packages/shared
Pruning stale branches across all repos
The prune command deletes local branches classified as stale or very stale. It never touches remote branches.
# Dry run first to preview what would be deleted
git-branch-dash prune --dry-run
# Prune a specific repo
git-branch-dash prune --repo my-app
# Prune all repos (prompts for confirmation per repo)
git-branch-dash prune --all
Scanning on a schedule
The dashboard server runs a background scanner on a configurable interval. The default is every 15 minutes. Change it in Settings or via environment variable:
GBDASH_SCAN_INTERVAL=5 git-branch-dash start
Set to 0 to disable automatic scanning.
Reading branch data from the API
All branch data is available via the REST API at http://127.0.0.1:7654/api/:
# All stale branches
curl http://127.0.0.1:7654/api/branches/stale
# Branches for a specific repo
curl http://127.0.0.1:7654/api/repos/{id}/branches
CLI Reference
| Command | Description |
|---|
git-branch-dash start | Start the dashboard server |
git-branch-dash start --port 8080 | Start on a custom port |
git-branch-dash scan | Scan all configured repositories immediately |
git-branch-dash scan --repo <name> | Scan a single repository |
git-branch-dash prune | Interactive stale branch pruning |
git-branch-dash prune --repo <name> | Prune a specific repository |
git-branch-dash prune --dry-run | Preview branches to be pruned |
git-branch-dash prune --all | Prune all repos without prompting per-repo |
git-branch-dash repo add <path> | Add a local Git repository |
git-branch-dash repo list | List all tracked repositories |
git-branch-dash repo remove <name> | Remove a tracked repository |
git-branch-dash config set <key> <value> | Set a config value |
git-branch-dash config show | Show current configuration |
git-branch-dash --help | Show help |
git-branch-dash --version | Show version |
Environment Variables
| Variable | Description | Default |
|---|
GBDASH_PORT | Dashboard port | 7654 |
GBDASH_HOST | Bind address | 127.0.0.1 |
GBDASH_DATA_DIR | SQLite and config directory | ~/.git-branch-dashboard |
GBDASH_GITHUB_TOKEN | GitHub token (overrides config file) | (from config) |
GBDASH_GITLAB_TOKEN | GitLab token (overrides config file) | (from config) |
GBDASH_SCAN_INTERVAL | Auto-scan interval in minutes | 15 |
GBDASH_STALE_DAYS | Days until a branch is stale | 31 |
GBDASH_VERY_STALE_DAYS | Days until a branch is very stale | 90 |
GBDASH_LOG_LEVEL | Log level: debug, info, warn, error | info |
Staleness Tiers
| Tier | Age | Color |
|---|
| Fresh | 0-7 days | Green |
| Aging | 8-30 days | Yellow |
| Stale | 31-90 days | Orange |
| Very stale | 90+ days | Red |
Thresholds are configurable per-instance via Settings or environment variables. The default branch (main/master) is never classified as stale regardless of last commit date.
Troubleshooting
"No repositories tracked" - Add at least one repository with git-branch-dash repo add <path>. The path must be an absolute path to a local Git clone.
PR badges not showing - Configure a GitHub token: git-branch-dash config set github-token ghp_.... Verify the token has read:repo scope and the repository owner/slug are correct in the repository settings.
Scan fails with "not a git repository" - Verify the path passed to repo add contains a .git directory. Submodules must be added individually if they have separate remotes.
Stale thresholds not updating - After changing thresholds in Settings, trigger a manual scan with git-branch-dash scan so all branches are reclassified against the new values.
Port 7654 already in use - Start on a different port: GBDASH_PORT=7655 git-branch-dash start or set it in the config file.
Database locked error - Only one instance of git-branch-dash should run at a time. Stop any existing instance before starting a new one.
