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), counted from the moment the last refresh landed — or from the moment you change the interval. Press r for an on-demand refresh any time; the next automatic one then counts from yours. Only one timer is ever live, however often you refresh or change the interval.

Opens on your last dashboard

Since v0.39.0 the dashboard you saw last appears at once, while the live fetch runs — on a busy account that fetch takes ten seconds or so. The footer says it is a snapshot, cached 3h ago · refreshing…, until the live answer replaces it. Nothing pulses and nothing notifies on that switch: those mean a change seen while you were watching. With no network the snapshot stays up and the footer reads offline · retrying · cached 3h ago.

The snapshot is the last successful fetch. A launch starts from it only while it is under a week old, only on the octoscope version that wrote it, and only for the same token looking at the same account. It lives in your user cache folder, in a file only you can read, because it holds what the dashboard shows, private repository names included. It is never read or written under --public-only, nor by --json, --plain or --scan. Turn it off with dashboard_cache = false, which also deletes it.

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 a refresh runs into the primary rate limit, auto-refresh backs off until the reset time GitHub last reported instead of hammering the API every 60 seconds — whether that refresh was automatic or yours; after a secondary limit it waits one interval, and at least 60 seconds. It reacts to the limit's error rather than to the budget counter, and the reset time arrives with a successful refresh, so a session whose very first fetch already hits the primary limit retries at the interval. 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.

These are not the same thing as the Inbox tab, and the difference is worth holding onto. What is described here is octoscope noticing a number change between two of its own refreshes — nobody sent it to you. The Inbox is GitHub's own notification feed: mentions, review requests, assignments — things somebody actually addressed to you. One is a delta octoscope computed; the other is a message GitHub delivered.

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 dashboard stays where it was and the footer says why — and what to do about it — followed by how old what you are looking at is (updated 2m5s ago). The full-screen error appears only when there is nothing to show yet.

rate-limited · retry at 14:23 — wait; it resumes on its own.
token rejected · check $GITHUB_TOKEN — fix auth (or run 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.

Is it GitHub, or is it octoscope?

octoscope does nothing but talk to GitHub, so when GitHub degrades every symptom — a timeout, an empty tab, a 502 — looks exactly like octoscope being broken. So it asks GitHub's own status page, and says which it is.

It is silent while GitHub is healthy, and silent again if the status page itself can't be reached: octoscope never renders a green "all systems operational", because that would be a clean bill of health it hasn't verified. You only ever see it when something it actually depends on — API Requests, Issues, Pull Requests, Actions, Webhooks — is degraded. An incident confined to Codespaces, Packages or Copilot changes nothing for a dashboard fetch, and doesn't warn you.

Two placements: a line under the banner while the impairment lasts, and — the useful one — a note on the error screen when a fetch has failed with nothing yet on screen, at the moment you're deciding who to blame. That note only appears for failures an incident could actually cause: a rejected token or a spent rate-limit budget is your problem, and blaming GitHub for it would bury a correct diagnosis under an irrelevant one.

It doesn't poll. One unauthenticated request at launch, on r, and after a failed fetch — plus, while a warning is on screen, on your own refresh cadence so it can disappear when GitHub recovers. Different host from api.github.com, so it costs nothing against your rate limit. Opt out with check_service_status = false; it's also suppressed under --public-only, which keeps recorded demos reproducible.