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).

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.

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 (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 already failed, 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.