Claude Usage HUD

Keep your Claude Code usage and active model in view, at a glance, without waiting for the "you've used X% of your weekly limit" banner.

It shows:

• Usage windows in the status bar: 5-hour, 7-day, and per-model (Fable / Opus) percentages, each color-coded green to red as you approach the limit.
• The active window's model: which Claude model this window is talking to, resolved per window and tracked through mid-session switches.
• A floating always-on-top HUD you can pop out and keep visible over everything.
• A panel dashboard with the full breakdown and every live session across your repos at once.

Two colors, two different jobs. The bar is how much of the window is gone. The countdown is your pace against the time left, which is why 44% can sit next to a calm blue and 91% next to an urgent one. A window can be nearly full and perfectly relaxed, or barely touched and burning too fast.

All three surfaces at once, so you can see where each lives. You would normally pick one.

🔌 Standalone: nothing to set up

The extension reads your own Claude Code login and calls the same usage endpoint the built-in /usage panel uses. There is no companion script, service, or account to install. If you have Claude Code and you are logged in, it just works.

Model and live-session detection are fully local, read from Claude Code's own transcript files.

👁️ Surfaces

Only the status bar is on screen by default. The HUD has one catch: it floats above ordinary windows, but not above a full-screen editor, because on macOS a full-screen window owns its own Space. Working full screen, set usageHud.floatMode to beside and it opens inside the editor window instead.

The status bar at micro density: the model this window is talking to, then each window as a dot and a percentage. The dot is pace, the percentage is level, which is why 91% is red next to a yellow dot. Wider densities add labels, bars and countdowns.

Hover the status bar for the detail, without opening anything. Plus every live Claude session across your repositories.

Anchored to the status bar item, so it never covers what you were reading.

The panel dashboard, in the Usage tab beside Terminal and Problems. Same data, plus how long each session has been idle.

An ordinary panel tab, so it docks, resizes and hides like Terminal does.

The legend button spells out both palettes, so the colors never have to be guessed: usage bands on top, what each countdown color says about your pace underneath.

🎛️ Commands

Click the status bar item and everything the extension does is one click from the number you were already looking at:

The click menu, shown with the editor full screen. The hover card carries direct links to Actions, Settings and Refresh too, so you rarely need to come here.

The same commands are in the Command Palette under Usage HUD, and Usage HUD: Settings is the quickest way to see every setting listed below.

⌨️ Keyboard shortcuts

On macOS, Ctrl+Cmd+U toggles the Usage panel. That is the one binding this extension ships. On Windows and Linux nothing is assigned, deliberately: the obvious substitutes are commonly claimed by the window manager, and guessing on a platform this project has not verified is worse than leaving it to you.

Run Usage HUD: Keyboard Shortcuts to assign your own, on any platform:

{ "key": "ctrl+alt+u", "command": "workbench.view.extension.usageHudPanel" },
{ "key": "ctrl+alt+h", "command": "usageHud.popOut" }

One binding only opens the panel, despite the shortcuts editor titling it "Toggle". For real toggling, bind the same key twice with complementary conditions:

{ "key": "ctrl+alt+u", "command": "workbench.view.extension.usageHudPanel",
  "when": "!panelVisible || activePanel != 'workbench.view.extension.usageHudPanel'" },
{ "key": "ctrl+alt+u", "command": "workbench.action.closePanel",
  "when": "panelVisible && activePanel == 'workbench.view.extension.usageHudPanel'" }

⚙️ Settings

Open them with Usage HUD: Settings, or search Settings for usageHud. Everything applies immediately, with no reload.

💡 Tip: make the hover card appear faster

VS Code waits 1500 ms before showing any status bar hover on macOS, which makes the hover card feel sluggish. Extensions cannot override it per item, but you can change it once for all of VS Code:

"workbench.hover.delay": 400

Or run Usage HUD: Make Hovers Appear Faster and pick a value. This is a global setting and speeds up every hover, not just this one.

🪟 The floating HUD, full screen and size

Full screen. On macOS a full-screen window owns its own Space, and a Space cannot be shared with a floating window, so a HUD popped out from a full-screen editor takes a Space of its own rather than floating above it. That is the operating system, and nothing here can override it. Set usageHud.floatMode to beside when working full screen.

Size. There is no API for an extension to size a floating window, so the geometry is VS Code's and yours. Your window.zoomLevel and whether the main window is full screen are what influence it.

📋 Requirements

• VS Code 1.80.0 or higher.
• Claude Code, installed and logged in.
• A Claude plan that includes Claude Code: Pro, Max 5x, Max 20x, Team, or Enterprise. Free does not include Claude Code at all.

You do not have to tell it which plan you are on. The endpoint reports whatever windows your account has and the extension renders those.

If you point Claude Code at an API key instead, this cannot help you. The windows it shows are plan limits, and an API key has none, so the percentages read usage unavailable. The model label and live-session list still work either way. docs/ROADMAP.md records why API spend would be a different product rather than another data source.

Platform support

Only macOS is verified. If it works for you on Linux or Windows, or it doesn't, say so in an issue: that is the fastest way for these rows to become honest. Nothing degrades badly if a platform turns out to be unsupported. The affected surface simply does not appear, and Usage HUD: Show Log says why.

🔐 Your Claude Code token

To read your usage it needs your Claude Code login, so here is the whole of it in four lines. It reads the token Claude Code already stores. It sends it to one host, api.anthropic.com, on one endpoint, to ask for your numbers. It is never written to disk, never logged, and never sent anywhere else. dependencies in package.json is empty, so no third-party code runs at all.

SECURITY.md has the detail: which keychain item or file, what happens if you deny the macOS prompt, and how to check the claim yourself in about five minutes.

📦 Install

From the Marketplace: search Claude Usage HUD in the Extensions view and click Install.

From a .vsix: Command Palette, Extensions: Install from VSIX. Every tagged release attaches one, built in public CI from that exact commit, so it is the copy to use if you would rather not take the Marketplace's word for what is inside.

🐛 Now that you have it, tell me what breaks

This is a small extension by one person, and the most useful thing you can send is not a patch. It is a sentence about what went wrong, or what you wish it did. Open an issue for anything.

Two asks in particular, because they are the ones I cannot answer myself:

• Does it work on Linux or Windows? Only macOS is verified. A one-line "usage windows are fine on Fedora 41" is genuinely more valuable right now than most code changes.
• Did a number look wrong? This extension's one promise is that it never shows you a figure as though it were reliable when it is not. If it ever does, that is the most serious bug it can have.

☕ Support

This is free and stays free. Nothing is gated, nothing is behind a plan, and nothing will be.

If it saves you one surprise rate limit and you feel like saying thanks, GitHub Sponsors is open. It helps keep the AI subscriptions running that this gets built with.

🔍 How it works, in short

Caching. Requests are cached and shared across every open window, so many windows never mean many API calls: at most about one refresh per minute in total.

When it cannot refresh. The HUD keeps showing the last good reading and marks it stale: a ~ in front of every value, and a warning in the hover card telling you how old it is. It will never quietly show a figure as though it were current, and it will never show 0% because it failed to read a number.

docs/ARCHITECTURE.md has the full design.

📚 Documentation

Read DESIGN_DECISIONS.md before proposing a UI change. Several obvious-looking ideas are settled there with reasons, including some that were built first.

👤 Author

Built by Marius Giurgi (@DolphinDream), one person, in the open. There is no support queue behind this: there is an issue tracker and me, which is why a one-line report is worth more here than it would be somewhere larger.

⚖️ License

MIT, see LICENSE.