github-overview

Local command center for N GitHub repos — commits, Actions CI status, dependency alerts, issues, and pull requests — as one self-contained Go binary.

A single serve process polls the GitHub REST API on a per-repo schedule, keeps history in SQLite, and renders a terminal-styled dashboard at http://127.0.0.1:6282 that updates live via Server-Sent Events.

See SPEC.md for the full technical specification and HANDOFF.md for current build status.

Setup

Requires Go 1.25+.

go build -o github-overview .

A GitHub token is optional but recommended — set one in Settings for useful poll rates:

export GITHUB_TOKEN=ghp_...   # or GH_TOKEN

You can also open Settings in the dashboard and save a personal access token. Saved settings are stored in the local SQLite database and take precedence over environment variables on the next launch; environment variables are the fallback when no token is saved.

Without a token, unauthenticated GitHub API limits apply and the effective poll interval is clamped to 15 minutes (a startup warning is logged either way).

Token scopes:

• repo scope (classic) if you're tracking private repositories.
• Dependabot security alerts additionally need security_events scope (classic tokens) or the fine-grained "Dependabot alerts: read" permission. Without it, alerts are silently skipped and the card falls back to showing only bot update PRs (dependabot[bot] / renovate[bot]) — this is an expected degraded mode, not an error.

Usage

./github-overview add golang/go                # track a repo (60s poll interval)
./github-overview add owner/name -interval 5m  # custom interval (min 15s)
./github-overview import                       # track every repo you own (needs GITHUB_TOKEN)
./github-overview list                         # tracked repos + last poll + errors
./github-overview remove owner/name            # dry run: prints what -f would delete
./github-overview remove owner/name -f         # deletes the repo + all history
./github-overview serve                        # run the poller + dashboard
./github-overview serve -v                     # ... with debug logging

import lists repos via GET /user/repos?affiliation=owner — only repos you directly own, not ones you merely collaborate on or that belong to an orgs you're a member of. Already-tracked repos are skipped, not duplicated.

A repo showing "not found" on its card means GitHub returned 404 — which it does identically for a repo that doesn't exist and a private repo your token can't see (this is intentional on GitHub's part, to avoid leaking whether a private repo exists). If a repo you know is real and private shows this, check your token has access to it.

serve flags: -addr (default 127.0.0.1:6282, binds loopback-only — non-loopback logs a warning since the UI has no auth), -db (default data/app.db), -workers (default 4).

Local worktree status

Each repository card can also surface local work that GitHub cannot see: unstaged, staged, and untracked files, plus commits ahead of the checkout's configured upstream (unpushed). Choose Find local checkouts on the dashboard to link matching github.com origins found up to four folders below your home directory, or enter an absolute checkout path from the repository's Local work tab. The check runs locally with git status; it never sends working-tree content to GitHub.

Port 6282 is reserved for this project in this machine's ~/.config/agent-rules/PORTMASTER.md.

Development

make check   # gofmt -l . && go vet ./... && go test ./... -race

Tests never touch the real GitHub API — internal/github is tested against httptest.Server fixtures.

Vendored assets

internal/web/static/vendor/ is checked in (not fetched at build time):

File	Source	Version
htmx.min.js	https://unpkg.com/htmx.org@2/dist/htmx.min.js	2.0.10
sse.min.js	https://unpkg.com/htmx-ext-sse@2/dist/sse.min.js	2.2.4

Roadmap

Each repo's detail page (/repos/{id}) has tabs for Commits, Actions, Dependencies, Issues, and Pull requests (any author — not just the bot-authored update PRs that count toward the dependency signal). Not tracked today: a cross-repo view aggregating issues/PRs across every tracked repo in one place. See ROADMAP.md for that and other discussed-but-not-yet-scheduled direction.