Usage limits

The menu shows your plan utilization as text bars above the Model menu, and the session percentage next to the menu bar icon — prefixed with ⚠ once you cross 80%.

Session  ▰▰▰▰▰▰▱▱▱▱  62% · resets 3:00 PM
Week     ▰▰▰▱▱▱▱▱▱▱  31% · resets Thu 8:00 AM

The two providers get these numbers in completely different ways, and the difference matters.

Claude: the official numbers, opt-in

These are the same figures /usage reports, with reset times. Getting them means reading Claude Code’s own OAuth token from the macOS Keychain and calling Anthropic’s usage endpoint with it — so it is opt-in and off by default.

Turn it on at Settings… → General → Permissions → Keychain → Allow access. It takes effect immediately, no restart, and triggers the one-time macOS Keychain consent dialog. Choose Always Allow.

Left off, a fresh launch shows no Keychain dialog at all — the usage section just shows a hint inviting you to enable it. If you previously denied the consent, you get a Grant access button instead.

When the token expires

BlackFlare asks Claude Code itself to refresh it. It invokes the claude CLI with -p in --safe-mode, on the cheapest model, from an empty scratch directory — so none of your hooks, MCP servers, or CLAUDE.md files run — then re-reads the freshly rotated token from the Keychain and retries. This happens whenever the token has expired, on a menu open or a background poll, and is rate limited to at most one claude spawn every 5 minutes.

It can only recover an expired access token whose refresh token is still valid. If the refresh token itself has expired or been revoked, the CLI can’t refresh silently either, and the section asks you to open Claude Code and sign in.

BlackFlare never writes to Claude Code’s Keychain item. The claude CLI owns the rotation and the atomic Keychain write — exactly what happens when you open Claude Code by hand, just automated. The token is never logged and never persisted (it is cached in memory for the app’s lifetime only), and it goes nowhere except api.anthropic.com.

Every failure here degrades the usage section alone. The switcher keeps working.

Codex: a local snapshot, no token

Codex usage is read from the rate_limits object Codex embeds in its own rollout files. No token, no Keychain, no network. Bar labels come from each window’s duration (5h, Week, Month).

The trade-off: it is fresh while Codex is running and stale when Codex is idle. The “Updated Xm ago” subtext exists to be honest about that rather than present a stale number as current.

Turning polling off

Settings… → General → Show usage in menu bar icon removes the percentage from the menu bar and stops all background polling (which otherwise runs every 5 minutes). The in-menu bars stay, refreshing only when you open the menu.

Note that usage-threshold alerts keep polling even with the menu bar percentage hidden — see Notifications.