Omniscio

Usage Forecast (predicted rate-limit exhaustion) (part 2)

Part 2 of the Usage Forecast page: how to read each per-account forecast state, the threshold that fires an early warning, the data-freshness line, the four-card Usage Stats page, the optional header widget and the architecture behind it all.

On this page

What it is

This is part 2 of the Usage Forecast (predicted rate-limit exhaustion) page. It covers how to read each per-account forecast state, the threshold that fires an early warning and when it does and does not fire, the data-freshness line, the four-card Usage Stats page, the optional header widget, and the architecture behind the per-account slope, the pool rollup, the warning dispatcher and the renderer hosts.

Where to find it

The same surface as the full page: the Accounts popover off the utilization chip in the top-right of the main window, the per-account row in Settings → Accounts, the two controls in Settings → Notifications, the Usage tab under the Statistics sidebar group, and the optional header Usage widget you add from the header overflow menu or Settings → Widgets.

How it behaves

How to use it

  1. Where the per-account forecast row appears. The same projection row is rendered in two places so you can read it without leaving your current view:

    • Top-bar Accounts popover — click the utilization percentage chip in the top-right of the main window (e.g. 91% v) to open the floating Accounts panel. The global banner sits at the very top; below it, each OAuth account row shows the 5h/7d/Extra mini-bars, and the forecast row sits directly under those bars in the same row card.
    • Settings → Accounts — open Settings, scroll to the Accounts section. Same row of text appears just below the colored 5h usage bar on each OAuth account card. (The global banner is popover-only — it does NOT appear in Settings → Accounts.)

    API-key accounts do not show a forecast row in either location — API keys don't have a 5-hour rate-limit window to project against.

  2. What each per-account forecast state means.

    • Limit reached (red) — you are already at or above 100% utilization in this 5-hour bucket. Nothing left until the reset.
    • Calculating… (muted grey) — Omniscio has fewer than ~10 minutes of signal inside the current window. Slope estimates from short samples are noise, so the forecast holds off.
    • won't reach limit before reset (muted grey) — at the current burn rate, the bucket will reset (refill) before it ever reaches 100%. You're safe to keep working at the current pace.
    • ~X.Xh until exhausted, resets in Yh (amber) — your standard projection. Burn-rate math says you'll hit 100% at the displayed ETA, and the bucket will reset at the displayed time. Both are rough — they assume your current rate continues. (When the ETA is between 30 minutes and 1 hour, the unit switches to minutes — e.g. ≈45 min until exhausted, resets in 4h. The "Almost out" prefix only kicks in below 30 minutes.)
    • Almost out — ≈X min until exhausted, resets in Yh (red) — projected exhaustion is 30 minutes or less away. The "Almost out" prefix is intentional so urgency isn't communicated by color alone (matters for color-blind users and screen-readers).
    • · data N min stale (suffix) — your last successful usage poll is more than 30 minutes old, so the projection is using older numbers than usual. Refresh the account or wait for the next poll cycle.
    • · unusual rate (suffix) — the burn-rate exceeds 80%/hour, which is suspiciously fast. Could be a runaway agent, another machine logged into the same account, or a real intense session. Worth a glance.
  3. Early-warning setting. Open Settings → Notifications and scroll to the bottom:

    • The Usage forecast master toggle (default ON) controls whether the inline row AND the global banner appear at all and whether the warning dispatcher runs. Turn it off and you go back to plain percentage bars with no projection text and no global banner.
    • Under the toggle, the 5-hour exhaustion warning number input (range 0–5 hours, step 0.5, default 0) sets your alert threshold. 0 disables the dispatcher entirely but the inline forecast row still displays. Set it to (for example) 1 and the dispatcher activates when the projected exhaustion drops below 1 hour inside any 5-hour window.
    • The threshold input is nested under the master toggle and is hidden when the toggle is off (because the dispatcher can't run if the feature is off).
  4. When the warning dispatcher fires (and when it doesn't). Omniscio's main process emits a usage-forecast:warning push event (channel IPC.USAGE_FORECAST_WARNING) when all of the following are true at once:

    • The forecast state is projected (we have enough signal to compute slope).
    • The forecast says willExhaustBeforeReset = true (you're on track to hit 100% before the window resets).
    • The projected hoursUntilExhaustion is less than your configured threshold.
    • The forecast is NOT flagged as unusualRate (we suppress alerts when burn looks anomalous to avoid noisy alarms — the inline row still shows the "unusual rate" suffix though).
    • You haven't already been warned for this exact 5-hour window. Dedup is per-account, per-bucket, keyed on the window's resetsAt timestamp — a new window unlocks a fresh warning automatically.
    • The Usage forecast master toggle is on AND the threshold is above 0.

    What you actually see: an inbox card. When the dispatcher fires, Omniscio raises a card in Alerts — it names the login and the window ("you@example.com is close to its 5-hour usage limit"), says roughly how long until the allowance is used up and when it resets, and offers a one-click Open Accounts settings button so you can move work to another login. One card per login per window: a re-fire in a later window updates the same card instead of stacking a new one, and when a window rolls over without a fresh warning the card is withdrawn — a warning never outlives the window it describes. Removing the login withdraws its cards at once as well, and on the next launch Omniscio also withdraws any card left behind for a login that is no longer there, so a warning never outlives the login it names. Turning off the Usage forecast master toggle stops the card along with the rest of the feature, and the type has its own switch on the Alerts settings list if you want to silence the card alone.

    (The main process still emits the usage-forecast:warning push alongside the card; that event has no desktop renderer listener and exists for the push fan-out.)

    (Warnings fire from per-account state only. The global banner is informational; it does NOT have its own warning dispatcher.)

  5. How to disable. Two levels:

    • Hide everything (rows + banner): Settings → Notifications → Usage forecast toggle → off. The global banner, the inline rows under each account, and the warning dispatcher all go silent.
    • Silence the dispatcher (rows and banner stay): Settings → Notifications → 5-hour exhaustion warning → set to 0. Rows and banner still display so you can read projections; the dispatcher just doesn't fire.
  6. The "What this banner means" explainer. A small "i" sits beside the banner's verdict line and reveals a plain-English legend that decodes the whole banner: the health check + color, the rolling 5-hour limit (a window that refills every 5 hours, so hitting it is a brief pause on one account — not running out of Claude), the weekly limit (the one that can pause you for days), what coverage % means (over 100% is comfortable, under 100% runs tight before reset), and what "sessions left" estimates. It exists because the green "healthy" glyph next to a ~2.5h until your 5-hour limit headline read as a contradiction. It adapts to the device: on a hover-capable device the "i" reveals the legend as a tooltip (hover or keyboard-focus); on a touch device it is a tap-toggle that expands the legend inline (a hover bubble can't open on a tap). It appears in every state where a verdict renders, and the legend copy is deliberately conceptual (no exact numbers) so it stays accurate even if the tier thresholds change.

Data freshness ("Updated Xm ago")

The bars and the forecast are only as current as the last successful poll, so the Accounts surface tells you when it was last refreshed — you can trust (or distrust) the numbers at a glance instead of guessing whether a static-looking bar is fresh or frozen:

  • The top-bar popover footer and Settings → Accounts (on the "Login Accounts" header) both render a small Updated Xm ago line. It's driven by the oldest login account's fetch time — the honest worst case for the whole pool, not just the active account — and re-renders every ~30 seconds so it visibly ticks up while the panel sits open (a label that never moves itself reads as "frozen").
  • It stays calm grey at normal cache age and turns amber only once that oldest account is more than 30 minutes stale — the same 30-minute gate that drives the · data N min stale banner suffix. Before the first successful fetch it reads Not checked.
  • The Refresh button beside it forces a fresh fetch of every account and spins while the fetch is in flight.

Expect a healthy pool to usually read Updated ~10–14m ago and tick upward: Omniscio samples each account every ~15 minutes and the renderer re-polls every ~5 minutes behind a ~10-minute cache, so a 10–14-minute age is the normal cadence, not staleness. The amber threshold (30 min) sits deliberately well past that, so amber means something genuinely stalled.

Usage Stats page

The Accounts popover gives you a one-line forecast, but for the full picture there's a dedicated Usage Stats sub-page reached from the Statistics virtual project in the Omniscio sidebar group — once open, the project's middle column shows two tabs at the top (Overview and Usage); click Usage to land on the page. The page is a 2×2 grid of four cards, each a self-contained chart with its own data fetch. Together they answer four different questions about your pool: where is the burn heading, when does it usually peak, which account is closest to capping, and how does the next week look at a glance.

  1. Pool Trajectory (Last 14 days → Next 7 days) — stacked line chart with one row for the 5-hour bucket and one for the weekly bucket. Both lines plot pool % used: the plain average of every account's usage in that bucket (each account carries the same 100 points; an account that cannot spend the bucket — at its limit, or weekly-locked for the 5-hour row — counts as 100%). A solid line traces the past 14 days of actual pool usage (the same 14-day window the model learns from), a dashed line continues into the next 7 days as the HOD-walk projection, and a translucent band around the dashed segment shows the high/low standard-deviation envelope. A single vertical "now" marker spans both rows. Per-row green-dashed verticals mark account resets; a red-dashed horizontal sits at 100% on each row. A corner toggle highlights one bucket at a time, but both rows always render.
  2. Burn Rate Heat-Map (HOD × DOW) — two 24×7 grids stacked top-to-bottom (5h on top, weekly below); the backend sends a full grid for BOTH buckets. Each cell's value is the whole pool's mean burn in that hour-of-day × day-of-week (summed across every account), and its shading is scaled to the data: each grid's own 95th-percentile cell is full colour and everything else is shaded relative to it, so a busy multi-account pool shows its peaks instead of one solid block. The tooltip number is never rescaled. Outlined-amber cells flag low-confidence cells with only one sample; dashed-empty cells mean no samples at all. Hover any cell for a tooltip with the mean burn in pp/h and n, the number of days it comes from (n=1 is marked preliminary).
  3. Per-Account Pool Contribution — one horizontal bar per OAuth login account. Each bar shows the account's current utilization as a solid fill, the projected addition through the bucket horizon as a striped overlay, and the 100% headroom as a thin outline. Color tiers: green below 70%, amber 70–95%, red above 95%. Reset times sit as text beside each account label. A toggle picks 5h or 7d — one bucket at a time.
  4. Daily Pool Projection (Next 7 days) — one vertical bar per local calendar day, starting with your local today (bars cut at your local midnight, not UTC midnight; each bar's bare YYYY-MM-DD is read back as a local date for its label), height = projected weekly-bucket utilization for that day, color-tiered identically to the per-account bars. A green dot sits below any day where one or more accounts reset.

All four cards share a single pool walk (walkPoolNativeWithTrace) so the chart you read against the heat-map matches the trajectory line above it — no source-of-truth drift between views. Each card fetches independently, so a single failed fetch leaves the other three intact.

Audit callouts. Each card renders an amber inline notice below its chart when its detector fires. Trajectory fires when the projected slope would breach 100% inside the bucket's planning horizon AND the recent-window mean burn is more than 20% above the historical rate — signal: "you're burning hotter than usual right now". Heat-Map fires when the last 90 minutes of pool burn run more than 30% above the cell containing "now" — both sides in pool points per hour — signal: "this hour is busier than your usual pattern". Both the Trajectory and Heat-Map detectors read the recent burn the main process sends with the trajectory (recentBurnPpPerHour: each account's raw rise in that bucket over the recent window, summed, skipping an account whose window spans a reset), never the slope of the drawn pool line — that line steps when an account hits or leaves its weekly cap, and the step is not burn. The Trajectory detector divides it by poolAccountCount to compare it with the projected line in pool-% per hour. Per-Account fires when any one account is at ≥90% utilization in either bucket — signal: "one account is about to cap out". Daily fires when more than half of the projected 7-day bars exceed 90% AND the headline coverage is below 100% — signal: "the next week looks tight". (Daily currently receives null for headline coverage in v1, so it stays dormant pending a v2 follow-up.)

Cold-start gating. When fewer than 7 distinct calendar days of usage samples exist inside the 14-day window (distinctDays < 7), all four cards collapse simultaneously to a Learning your patterns — N more days needed hint. The gate is centralized in the tab component off the heat-map payload's distinctDays, so the four cards never go out of sync — either they all show their chart or they all show the cold-start hint.

Where to find it. Two entry points open the page: the AccountIndicator popover has a View usage stats → link row in its footer, directly above the Updated-timestamp + Manage Accounts row; and Settings → Accounts has an Open Usage Stats → link button inside the Accounts heading block, after the description text. Both navigate to the Statistics virtual project and switch the Statistics tab to Usage.

Where the code lives.

  • The tab host: UsageTab.tsx.
  • The four chart components: UsageTrajectoryChart.tsx, UsageHeatMap.tsx, UsagePerAccountBars.tsx, UsageDailyProjectionChart.tsx.
  • The pure audit detectors: usage-audit.ts.
  • The four IPC channels — IPC.USAGE_FORECAST_GET_TRAJECTORY, IPC.USAGE_FORECAST_GET_HOD_CELLS, IPC.USAGE_FORECAST_GET_PER_ACCOUNT, IPC.USAGE_FORECAST_GET_DAILY_PROJECTION — and their handlers in usage-forecast-handlers.ts.

Usage widget (optional header chip)

A third place usage can appear — a compact, always-visible chip in the top header row, for people who want a running read on capacity without opening the Accounts popover or the Stats page. It is opt-in and off by default: you add it from the header's ⋯ overflow menu or Settings → Widgets (it is a normal header widget, so it shows / hides / reorders exactly like the account pill and the Hardcore indicator — see the header-widget contract for the mechanics).

  • What it shows. The account in use — its own 5-hour and weekly usage, each with a reset countdown, coloured by the same threshold gradient used everywhere else (green < 60 · yellow 60–69 · orange 70–89 · red 90+). It is the same account the account pill shows, so the two never disagree (owner decision 2026-11-16; it used to show a pool average). Which Claude usage applies follows your sign-in method: a stored login (one own login, or the owner's pool) shows the active account; the Claude Code login shows that login's own usage; an API key, a CLI proxy or the account add-on show no subscription usage. When you also use Codex, the popover adds the Codex bars below Claude; a Codex-only person sees Codex on the chip itself.
  • How the number is built (src/renderer/src/lib/claude-usage-for-method.ts). One selector, selectClaudeUsageForMethod, answers usage, loading, unreadable or none from the resolved sign-in method, and the header widget, the account pill and the phone account chip all read it. The Claude Code login's reading comes from APP_CLI_USAGE (main's fetchCliUsage, which parses with the same schema and mapper as stored accounts); the renderer keeps the last good reading when a later read comes back empty, and the popover says it can't read your Claude Code usage right now only when it holds nothing (a Mac login kept only in the Keychain, or an expired login). A window the account does not report is hidden rather than shown as 0%.
  • Click / hover. Click opens the full Stats → Usage page; the chip's popover shows the full 5-hour + weekly bars, reusing the same MiniUsageBar as the Accounts popover.
  • Field options (which fields it shows). Three toggles in Settings → Widgets → Usage widget — Show 5-hour usage, Show weekly usage, Show reset countdowns (all on by default; settings usageWidgetShowFiveHour / usageWidgetShowWeekly / usageWidgetShowResets). Turn any off to slim the chip down to just the fields you care about.
  • No new data of its own. It reads the per-account allUsage the app already polls (the ACCOUNT_USAGE_UPDATED push), the Claude Code login reading fetched beside that login, and the Codex limits the account popover already holds — no new IPC, DB, or background loop. It is hidden on-camera under the same presentation-mode setting as the account widget (usage numbers are sensitive on a screen share).
  • Discovery (one-time tip). Because the widget is opt-in and off by default, a one-time, dismissible tip surfaces on a later launch to point new users to it: a single informational toast ("add a Usage widget to your header…") with a one-click Add it that pins it. It fires at most once per install (localStorage amc-usage-widget-discovery-tip-shown), desktop only, waits ~30s after the dashboard mounts, never fires over onboarding / a sign-in gate / an open modal (it retries a few minutes later), and never fires if you already pinned the widget yourself.
  • Where the code lives. UsageHeaderWidget.tsx (the widget), claude-usage-for-method.ts (selectClaudeUsageForMethod — which Claude usage applies to the sign-in method), the usage catalog entry + HEADER_WIDGET_BLOCK_IDS in toolbar-catalog.ts, the three toggles in ToolbarSettings.tsx, and the discovery tip in useUsageWidgetDiscoveryTip.ts (wired in App.tsx).

This is part 2 of the Usage Forecast (predicted rate-limit exhaustion) page — what the feature is, where to read it, and the verdicts and algorithms behind the headline live there.

Last verified 2026-10-02