Guide
Live & reliable
octoscope keeps itself current in the background and tells you the truth about what's happening — fresh numbers, honest errors, and a nudge when something changes.
Auto-refresh
The dashboard re-fetches on an interval (60 seconds by default; set refresh_interval or --refresh), so the numbers on screen are never more than that stale. Press r for an on-demand refresh any time. Exactly one timer runs no matter how often you refresh or change the interval.
Rate-limit awareness
The footer shows your live GitHub API budget — rate 4872/5000 · reset 23m — coloured muted normally, warn under 20%, and critical under 5%. Press % for a per-resource breakdown (core, GraphQL, search).
If you hit the ceiling, auto-refresh backs off until the bucket refills instead of hammering the API every 60 seconds. Transient 5xx blips from GitHub's gateway are retried automatically before anything surfaces.
Live feedback
When a value changes between refreshes — a new star lands, someone follows, a PR merges — the affected card's border flashes accent-pink for two seconds. No diffing numbers with your eyes.
Changes to your Stars and Followers also fire a native system notification with a short beep, so you catch passive attention even when octoscope is in a background tab. It works on macOS, Linux and Windows and is click-through to the relevant page.
macOS: native notifications use terminal-notifier. Homebrew pulls it in automatically; if you installed octoscope another way, brew install terminal-notifier once and you're set. Without it, the in-app change-pulse still works.
Honest errors
When a refresh fails, the footer says why — and what to do about it:
rate-limited · retry at 14:23— wait; it resumes on its own.token rejected · check $GITHUB_TOKEN— fix auth (orrun gh auth refresh).token lacks a scope— the missing scope is named.offline · retrying/github errored · retrying— network or gateway; it keeps trying.
A watch_repos entry that no longer resolves (renamed, deleted, gone private) surfaces a small notice naming the stale ref, instead of silently vanishing.
Update check
octoscope checks for a newer release at launch and hourly, and shows a quiet notice with the right upgrade command for how you installed it (brew upgrade, go install, …). It never self-updates. Opt out entirely with check_for_updates = false in your config.