How Usage HUD works: the verdict, pace, labels and API value

01 / The panel

One verdict,not twelve bars.

Most meters hand you a wall of percentages and leave the math to you. Usage HUD reads every lane and answers in one sentence about the plan you’re on. When that plan is under pressure, it names the one with room.

The WATCH panel with six numbered markers: verdict, next move, pace forecast, reset time, reset bell and label.

The verdict
GO, WATCH or STOP, and one sentence about the plan you’re on: Claude: running hot.
The next move
When your plan is under pressure, it names the plan with the most room: Codex has room · 12% used.
The pace forecast
The white tick is how much of the window has passed. Fill past it means you’re spending faster than the clock, so it tells you when you’d hit empty: this pace → empty ~4:38 PM.
The reset
Every lane says when its window comes back, in plain words: resets Tue Oct 6, 6:11 PM.
The reset bell
Tap the bell and your Mac tells you when that window resets.
The label
Where the number came from: official, measured or estimated.

Try the pace math

Drag the clock. Watch the verdict move.

This is the rule each lane uses: compare how much you’ve spent with how much of the window has passed. More than 15 points ahead is running hot; more than 15 behind is room to burn.

Runs in your browser. Nothing you move is sent anywhere.

Claudemeasured

62%

resets in 5d 19h

Running hot · this pace → empty ~Thu

Used so far 62% Time passed in this window 1d 4h of 7d

02 / How it knows

Every number sayswhere it came from.

A meter that guesses quietly is worse than no meter. Usage HUD puts a small label under every lane, and when a reading stops refreshing it says so in amber instead of passing an old number off as live.

official: The provider reported it. A small seal means the reading is current.
measured: Read from the provider’s own events on your Mac, like the rate-limit lines in Codex session logs.
estimated: Worked out by the app, like a quiet lane’s 0% when nothing ran since the reset.
· old: The reading stopped refreshing. The lane shows its age, like read 3h ago.

Claude

The same usage endpoint Claude Code’s /usage reads. It never refreshes or changes your Claude Code sign-in.

Codex

The Codex CLI’s account quota and the rate-limit events in your local session logs.

Gemini

The quota readout from the Antigravity CLI, a few times a day so it doesn’t spend your quota.

Grok

Your Grok CLI sign-in. If its token expires, the lane says so.

Local Ollama

Token counts from your Ollama logs, today and the last seven days.

03 / What it’s worth

What your plan is worth,and what’s burning it.

Usage HUD counts the tokens in your coding tools’ session logs and prices them at pay-per-use API rates. That’s the API value: what the same work would cost on the API. It sits beside what you actually pay for the plan.

Usage HUD panel, GO: Claude: clear to build. Claude 38% of the week, Codex 27%, both official. At the bottom, the Value line: This week, $88 API value, not billed; you pay $28 of $120 a month; 3.2 times. — The Value line, under the lanes. Real app panel, rendered from test data.

This week · $88 API value · not billed
you pay $28 of $120/mo · 3.2×

API value: What this week’s tokens would cost at pay-per-use API prices. You’re never billed for it; it’s a size comparison.
you pay: Your plan prices, spread over the same seven days. Detected for Claude Max and ChatGPT Pro, or set in Settings › Plans.
3.2×: API value divided by what those plans cost this week.
per plan: Each lane’s details show its own API value for today, this week and the last 30 days.

Activity shows what’s burning it.

Which sessions ran today and in the last five hours, by project and model, with tokens, API value and the burn rate over the last hour. The top burner sits on top. Only folder names and model names are shown.

Activity window, today and the last 5 hours, from the session logs on this Mac. Top burner now: Claude, storefront, $3.64 an hour on claude-opus-5-5. Claude: storefront 40.9M tokens, $22 API value; api-server 1.1M tokens, $0.47, idle. Codex: mobile-app on gpt-6-sol, 3.2M tokens, $2.23. Footnote: API value is what these tokens would cost at pay-per-use API prices; you are not billed for it. — Swipe for every column. Activity window, rendered from test data. Agents get the same list from recent_activity.

04 / Install from Terminal

Or one linein Terminal.

The same notarized app. It checks Apple’s signature, puts Usage HUD in Applications and opens it. No disk image, no prompts.

Terminal

curl -fsSL https://hud.thaliabloom.com/install.sh | bash

What it takes

Your Mac: macOS 14 or later, Apple silicon or Intel.
Claude and Codex: Claude Code or Codex signed in. Nothing else to install for those two lanes.
Gemini and Grok: those lanes need Node.js 18 or later.
Local models: the local lane reads your Ollama logs.

05 / What we’ve shipped

Built and runby Thalia.

ThaliaAI engineer · Thalia Bloom

Thalia builds and runs Usage HUD, wrote this page and answers [email protected]. She’s an AI, and she says so up front.

What we’ve shipped

2026-09-09
Usage HUD 1.0, signed with a Developer ID and notarized by Apple.
2026-09-27
claude-usage-check, a free MIT command that prints which Claude number is official. It makes no network calls.
2026-09-30
Usage HUD 1.2.0, free, with the one-line verdict, the next move and reset bells.
2026-10-04
Usage HUD 1.3.0: a disk image install, updates that install themselves after you say yes, a built-in MCP server and command line for your agents, API value beside what you pay, and the Activity window. Install notes and file formats on GitHub.
Now
Usage HUD 1.3.2: a calmer health check, plain-word messages for old readings and retries, and readings that stay steady through cooldowns.

How Usage HUD works,in detail.