Where does Usage HUD get the Claude Max number?

From the OAuth usage endpoint on api.anthropic.com that Claude Code’s /usage panel reads, using the login token Claude Code stores in the macOS Keychain. The HUD never refreshes or rewrites that token.

Does Usage HUD send my usage anywhere?

No. Readings stay on your Mac. There is no Usage HUD account and no telemetry.

What does the confidence label mean?

Official means the number came from the provider’s usage endpoint. High, medium, and manual mark local or hand-entered readings, each with a one-line reason.

Claude Max usage

Check Claude Max usage without opening claude.ai

There are two built-in ways to see Claude Max usage: the settings page on claude.ai and the /usage command inside a Claude Code session. Both mean leaving what you were doing. Usage HUD is a $9 Mac menu-bar meter that reads the same usage endpoint Claude Code’s /usage panel reads and keeps the numbers one click away.

It runs on your Mac only. There is no Usage HUD account and no telemetry. If you only use Codex and CodexBar already works for you, you do not need this.

What the app reads

Claude Code stores a login token in the macOS Keychain. Usage HUD reads that token and calls the OAuth usage endpoint on api.anthropic.com that Claude Code’s own /usage panel calls. The HUD never refreshes or rewrites the token; Claude Code owns that. The response carries a session limit (the 5-hour window) with a percentage used and a reset timestamp, a weekly all-models limit with the same two fields, and on some plans a model-scoped weekly limit as well.

The HUD shows those as 5-hour limit, Weekly · all models, and, where present, a line such as Fable weekly. Each line has its percentage, the reset time from the endpoint, and the time the reading was captured. The fetch runs from a Claude Code status-line hook and a background writer, so the number updates while you work instead of only when you ask.

Confidence labels

Every number in the panel carries one of five labels: official, high, medium, manual, or unknown, plus a one-line reason. The Claude reading is official, with the note “Fetched from the usage endpoint Claude Code’s /usage panel reads.” A Codex reading parsed from local session logs is high, with the note that it is not an official billing API. The label is there so a local estimate never looks like a provider-reported number.

Freshness is separate from confidence. An official reading that is an hour old is still official, but the panel shows the age. When a window passes its reset time, the reading expires rather than staying on screen at an old value.

What the app cannot know

Why a number moved

Claude Desktop, the web app, and Claude Code share the plan windows. The endpoint reports the plan total, not which client spent it. The HUD shows the total and cannot break it down.

Anything behind the percentage

The endpoint returns percentages and reset times. It does not return token counts, message counts, or the formula. The HUD does not estimate those for Claude.

Anything when the token is dead

If the Keychain token has expired because Claude Code has not run in a while, the endpoint answers unauthorized. The HUD shows unauthorized and asks you to open a Claude Code session once. It will not refresh the token itself, and it will not show a zero that looks like a real reading.

Anything while the endpoint says back off

If the endpoint rate-limits the fetch, the HUD waits out the cooldown, keeps the last reading, and shows its age.

Buy Usage HUD

$9 USD · one time · personal license through 1.x

Apple silicon Mac, macOS 14+. Signed and notarized.

After you pay: the next page is your notarized .zip. Open it on your Mac. 14-day refund by email.

Launch price through 30 Sep 2026, then $15. If CodexBar already works for you, you do not need this.

Claude Code usage limit reached · Claude Code usage in the menu bar · When ccusage stops tracking Claude · Usage HUD home