The Claude HUD · terminal strip and VS Code sidebar
The instrument that watches the session.
A long agent session spends money and fills a context window whether or not anyone is watching, and by the time either one becomes obvious it is already the problem. I built this instrument to make both visible while there is still a decision to make. It has three displays: a strip of small gauges above the Claude Code prompt, a full panel one command away, and a sidebar in VS Code. Since 17 October the terminal strip is the one I work in.
All three read Claude Code's own files. The limit readings come from the account's usage endpoint, signed in as Claude Code already is. My plan is Ultra, and Anthropic removes the 5-hour window once it verifies the account; the strip draws a window only while the service reports one. Every display shares one refresh slot: the first to find the shared reading five minutes old claims it and asks, and the rest read what it wrote, however many windows are open. No server, no port, nothing listening.
The field note The HUD takes the strip apart stage by stage: where each number comes from, and how a reading is graded.
Three displays, one set of rules
3Above the terminal prompt
The strip
The effort level, then the cache, the 5-hour, weekly and model windows and the context as small bars with their figures, the resets and the session clock. When a reading needs attention, its alarm leads the row in colour. It refreshes once a minute, after every model response and whenever Claude Code measures the session. By default it hides itself inside VS Code, where the sidebar already shows the same figures.
One command, no Claude turn
The full panel
Every limit with where it lands, when it resets and its burn rate, the week drawn against its plan with a divider at each day, the weekend’s budget, the session’s tokens and cache economics, and every helper with its model, run time and tokens. Typing the command opens it at once, even while a reply is still being written.
In VS Code
The sidebar
The same readings as cards, each marked with its scope, for when the work happens in the editor. It is the original display, and the rules it graded with are the ones the other two now share.
Two displays of one number are how a setup ends up with two half-trusted numbers. So every rule that decides a colour, a landing or the words of an alarm lives in one module, which reads no file, calls no network and starts no process, so its tests drive it with plain values. The sidebar loads that module directly. Each terminal display imports a generated copy, and a commit check refuses any commit where a copy differs from its source.
The displays also share their burn-rate history. When each kept its own, they fitted different recent rates for the same window, 0.3 and 0.7 percent an hour, and so drew different landings from one reading.
What that module grades is where a window will land at the current pace, not how full it is now. Green runs up to the whole allowance, because allowance left unused at the reset is waste. Amber starts at 100 percent, and red at 128.6 percent, the landing that the weekend's 45 percent ceiling works out to on a week planned to spend 35 percent in its first two days.
What the sidebar shows
4Each card below is marked with its scope, because the same number means different things at different scales — how much of a five-hour account window is gone is a different question from how full this one conversation is, and a panel that mixes them teaches you to read neither.
Limits, with pace
The five-hour, weekly and model windows, each as used-now and where it lands at the current pace, plus the weekend’s share of the week — not just how much is spent but whether the rate lands inside the window.
Context
How full this conversation’s window is, measured against the real window size, which is the number that decides whether a long session is about to lose its footing.
Cache
Time until the prompt cache goes cold, what a cold start would re-send, and how much of each request is served from a warm cache rather than re-sent and re-charged — the single biggest cost lever on a long session.
Helpers
Every delegated agent this conversation spawned, running ones first, each opening to its detail and its own transcript, so a fan-out is visible rather than absorbed into one total.
Credential profile
Showed which account was doing the work, and switched it in one click. The terminal strip has no switch, and the sidebar’s was last pressed in July, so it is kept here as history.
Two readouts of one source
The HUD and the terminal status line both describe one session, so they share one source rather than computing twice: the status line keeps a copy of what Claude Code hands it, one file per session, and every HUD display reads that copy.
Five figures reach the tool's own status-line command and no transcript records them — the cost estimate, its own tally of lines it edited, the percentage used against the real window size, the cache read on the request in flight, and the model variant. The terminal line shows them at a glance. The HUD takes what it needs from the copy, such as the cache's expiry, and adds the rate limits with their landings, cache reuse and the helpers, as gauges, where a gauge can say more than a number can.
Without that copy the HUD still renders what it can work out from the transcripts and marks the rest as missing, and a test proves it.
Status line keeps
- BILL
- EDITS
- CONTEXT
- CACHE
- MODEL
No transcript records them; the line copies them for the HUD.
HUD keeps
- Limits, with pace
- Context
- Cache
- Helpers
Everything it can compute for itself.