git-branch

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.