Alerts

Alerts

How a level is decided

For every limit (and spend, when it has a budget):

level = max(level of the API's own "severity", level of the percent vs your thresholds)

Thresholds default to 80% warning and 95% critical (Settings → Alerts, 1 to 100, warning is kept below critical). Whichever is worse wins.

Sinks

Toggle desktop and ntfy per account in Settings → Accounts.

Sink	What it does
Desktop	Standard macOS notification with sound. Needs notification permission, otherwise it is silently dropped. Settings → Alerts shows the current authorization status.
ntfy	JSON POST to your server (default https://ntfy.sh) and topic. Priority 3 for warning, 4 for critical. Each account can override the default topic.
Toast	Floating panel at the top right with slide-and-fade and a sound, shown whichever app is frontmost. Global on/off in Settings → General.

Send Test Alert (Settings → Alerts) pushes a synthetic warning through all three sinks.

ntfy setup

ntfy is a free push service; the public server needs no account.

1. Install the ntfy app on your phone.
2. Pick an unguessable topic name. Anyone who knows a topic can publish to or read it, so treat it like a password. There is no registration step.
3. Subscribe to the topic in the ntfy app (and set the server URL if you self-host).
4. In Settings → Alerts set the server and default topic.
5. Self-hosted server with a login: paste an access token (stored in the Keychain, sent only to the server above). Optionally add a fallback topic URL (a full URL such as a public ntfy.sh topic); it is used when the server errors or times out.
6. Enable ntfy on the accounts that should push to your phone.
7. Click Send Test Alert and confirm it arrives.

De-dupe and re-arm

Each (account, limit) pair remembers the last level it alerted at, keyed to the reset window.

• Fires only when the level rises (none → warning → critical). The same level on a later poll in the same window does not re-fire.
• A window roll re-arms it: once resets_at moves to a new window and the level is above none, it can fire again.
• resets_at jitters by a second or two between polls, so a 120-second tolerance treats nearby values as the same window.
• Dropping below threshold clears the stored level, so climbing back up alerts again.
• The memory persists across relaunches, so restarting the app does not re-alert.

Extra-usage alert

The moment paid usage starts being consumed, you get one notification with the amount and the running monthly total. It stays quiet until spending pauses for 30 minutes. Toggle it in Settings → Alerts.

Auth alerts

A local account that fails with 401 on two consecutive polls, or a remote account whose refresh failed, alerts once at critical and goes quiet when the account is healthy again. A single 401 is usually Claude Code rotating its own token mid-poll, so the app re-reads and retries once before counting a strike.