Usage Alerts

  • Desktop, mobile and web
  • All plans
View as MarkdownFeature page

What it does

Warns you before a provider quota runs out. Every quota bar of the footer Usage panel (session, weekly, per-model, 5-hour, monthly, one set per signed-in account) carries a bell. When a bar crosses a threshold, AgentsRoom shows a card inside the app, sends a native desktop notification and a push to the paired phone, according to three separate switches. Defaults: 50 %, 75 % then 90 % of every bar, on from the first launch, no default at 100 % because the CLI says so itself at that point and a Quota Rules rule can take over. A threshold is announced once per quota window: 80 % at every refresh is one banner, not one every ten minutes, and a restart does not repeat it. Since 1.180.0. The other way round, when a bar that had reached 90 % or more comes back (its window reset), AgentsRoom announces {provider} quota reset on the same channels, with a short success sound: "You can code again".

Where to find it

  • Footer usage badge > Usage panel: a bell sits on every quota bar, between the pin and the percentage. Grey bell: the bar follows the default thresholds. Ringing bell: the bar has thresholds of its own. Crossed bell: the bar is muted, or alerts are off globally.
  • Settings > Notifications > Usage alerts: the master switch, the default thresholds, the three channels, and the count of bars that have their own thresholds.
  • In the header of the Usage panel, a read-only Usage alerts switch reflects the master switch; clicking it closes the panel and opens Settings > Notifications > Usage alerts. It never changes the setting from the panel.
  • The in-app card appears at the top right of the window, like the "phone connected" card, with an Alert settings action. The "quota reset" card is a green success card with no action.

How to use it

  1. Sign in to your CLIs and open the Usage panel once so the bars load. Nothing else to enable: every bar already follows 50 %, 75 % and 90 %.
  2. To give one bar its own thresholds, right-click its bell (long press and keyboard work too). The menu Alert me when this line reaches lists 25, 50, 75, 90 and 100 % to tick, plus the values already set. Use the default thresholds (…) puts the bar back on the defaults, Mute this line silences it, Usage alert settings opens the settings block.
  3. To silence one bar, left-click its bell. Click again (Alert on this line again) to resume.
  4. To change the defaults, go to Settings > Notifications > Usage alerts and toggle the Default thresholds chips (25, 50, 75, 90, 100 %). At least one chip always stays on. Every bar without thresholds of its own follows the new list.
  5. Pick the channels: Show a card inside AgentsRoom, Show a desktop notification, Also send it to my phone. Turn off Alert me when a quota reaches a threshold to silence everything.

The notification title names the provider (for example Claude · AgentsRoom) and adds the account name in brackets as soon as that provider has more than one signed-in account. The body names the bar, the percentage, the threshold that fired and the reset time: "Current week (all models) is at 76% (alert set at 75%). Resets Sep 24, 04:00".

Since 2026-09-23 the in-app card is titled with the provider and shows its logo; on Windows and Linux the desktop banner uses the provider logo as its icon too (macOS always shows the AgentsRoom icon). With several accounts, each channel also says which account is concerned: the card adds a coloured dot (the account's colour) with the account name and email ("Work · [email protected]"), the desktop banner puts the email as a subtitle on macOS and as the first line of the body on Windows and Linux, and the phone push starts its body with the email.

The "quota reset" notice is titled {provider} quota reset (for example "Claude quota reset") and its body reads "You can code again: Current session is back to 3%." It fires only for a bar that had reached 90 % or more before its window reset; a weekly bar rolling over at 30 % says nothing. It uses the same three channels and the same account details as the threshold alerts, and plays a short jingle unless the notification sound is off (Play a sound when an agent finishes a turn) or the system is in Do Not Disturb. Turn it off with Tell me when a quota I had used up is reset in Settings > Notifications > Usage alerts. A muted bar announces neither.

When a bar has lines of its own, the settings block says "N lines have their own thresholds." with a Reset them link that puts every bar back on the defaults.

Settings

  • usageAlerts (global, Settings > Notifications > Usage alerts): { enabled, thresholds, overrides, inApp, desktop, phone, resets }. Default: enabled, thresholds [50, 75, 90], the three channels on, resets on (announce a quota back after it reached 90 % or more). overrides maps one bar (provider, account slot, window and model or limit group) to its own list; an empty list mutes that bar. Machine-local, not synced to the account.
  • notificationSound (global, Settings > Notifications > Sound): also gates the "quota reset" jingle.
  • sendNotificationsToPhone and mobilePushOverride (global, Notifications): the phone channel also obeys the general "send to phone" policy and the phone's own override.

Agent tools (MCP)

  • settings_get / settings_set: read or change usageAlerts (global switch, default thresholds, per-bar overrides, channels).
  • usage_overview: read the current percentage of every bar, to know which threshold is next. No tool sends an alert.

Providers

Every provider that publishes a quota to the Usage panel: Claude (current session, current week for all models, current week per model), Codex (5-hour window, weekly window, each limit group), Grok (weekly or monthly, for each signed-in Grok account, read from the Grok CLI proxy with that account's own session), Kimi (5-hour, 7-day, monthly), Cursor (the billing cycle: included usage, plus the Auto and API pools, read with the Cursor CLI's own sign-in), Antigravity (5-hour and weekly windows of each model pool, Gemini then Claude and GPT, read by asking agy for its /usage panel; needs agy 1.1.11 or later) and, since 1.184.0, OpenCode Go (5h limit, Weekly limit, Monthly limit, read from the subscription's usage endpoint with the key the OpenCode CLI stores after /connect). Since 2026-09-23 the Z.AI Coding Plan used through OpenCode has its own block too (5-hour and weekly bars, the plan level in its name), with its own bells. A provider added to the panel later is covered without any change, because the alerts read the panel, not each CLI. Providers with no quota signal (Mistral Vibe or Aider, for instance) have no bar and therefore no bell. A reading whose CLI session has expired says so on the account block ("session has expired") and comes back the next time an agent runs on that account: AgentsRoom never renews a provider's session itself. Since 2026-09-30, a plan that IS connected (the CLI stores its key) but whose reading fails keeps its OpenCode block visible and states the reason (refused key, network, no data) instead of leaving the section out, and the key lookup also follows the OpenCode CLI's own debug paths when the shell moves its data dir (XDG_DATA_HOME), so a store outside ~/.local/share is no longer invisible to the panel.

Mobile

The push reaches the AgentsRoom mobile app on iOS and Android with the same title and body as the desktop banner. Tapping it opens the Usage segment of the Activity tab, which mirrors the same bars as the desktop panel. The bells and the thresholds are set on the desktop only: the phone receives and shows, it does not change the rule.

Limits

  • The desktop app must be running (the bars are polled by it), in the foreground or in the background. The Usage panel itself does not have to be open.
  • One announcement per threshold per window. A threshold is rearmed when the provider publishes a new reset time (the window turned), when the threshold was removed then put back, and, for a bar with no reset time, when the percentage dropped about ten points below the threshold.
  • A bar that jumps over several thresholds between two refreshes (40 % to 80 %) sends one notification, for the highest one; the lower ones are marked as announced.
  • Thresholds are whole percentages from 1 to 100, chosen from the chips (25, 50, 75, 90, 100); there is no free text field.
  • Same behaviour on macOS, Windows and Linux. Not an email, not Slack, not a webhook: in-app card, desktop banner and phone push only.
  • Rules and thresholds live in the desktop settings of that machine and are not synced to the account.

Common questions

  • Do I have to turn it on? No. Alerts are on from the first launch at 50 %, 75 % and 90 % of every bar. What you may want to change is the channel, under Settings > Notifications.

  • Will I get a notification at every refresh once I am past 75 %? No. What was announced is remembered on disk, per window. The next one comes at the next threshold, or after the reset.

  • Can I set a threshold like 60 % or 85 %? Not from the interface: the chips are 25, 50, 75, 90 and 100. A value written through the usageAlerts setting stays visible as an extra chip so it can be turned off.

  • I have two Claude subscriptions, which one is the alert about? The title says so: the account name is added in brackets as soon as the provider has more than one account. Each account has its own bars, bells and thresholds.

  • What happens when the CLI renames a bar? Nothing. The rule is attached to what the bar is (provider, account, window, model or limit group), never to its label. A new model is a new bar with its own rule.

  • Does this switch my account at the limit? No. The alert only warns. Acting on a quota (blocking launches, moving to another account, changing the model) is done by Quota Rules, which send their own notice on the same channels.

  • Why does a bell show as crossed? Either that bar is muted (left-click to resume) or the master switch is off in Settings.

  • Can I be told when my quota is back? Yes, on by default: once a bar that reached 90 % or more resets, you get "{provider} quota reset, you can code again" with a success sound. Uncheck Tell me when a quota I had used up is reset to stop it.

Related