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.
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.
- Your login token is read from your machine's credential store (macOS Keychain, or
~/.claude/.credentials.json on Linux) and sent only to api.anthropic.com, never to any third party. The extension never stores it.
- On macOS you may see a one-time keychain permission prompt the first time it reads usage. That is you authorizing the extension to read the Claude Code credential.
- Calls are cached and shared across every open window, so many windows never mean many API calls: at most about one refresh per minute total. When the network is down, the HUD shows the last known values, marked stale.
Model and live-session detection are fully local too, read from Claude Code's own transcript files. No Claude Code extension API is required (there isn't one).
Surfaces
| Surface |
How to see it |
Always visible |
| Status bar composite |
Bottom bar, left side by default |
Yes |
| Floating HUD |
Command: Usage HUD: Pop Out Floating HUD |
Yes, floats on top |
| Panel dashboard |
The Usage tab in the bottom panel |
When its tab is open |
Click the status bar item for actions: pop out the HUD, open the panel, copy a report, or change the bar style and density.
Settings
| Setting |
Default |
What it does |
usageHud.density |
verbose |
Status bar detail: micro, minimal, bars, verbose (adds reset countdowns) |
usageHud.barStyle |
block |
Bar glyphs: block shade dot notch text |
usageHud.statusBarBars |
false |
Show glyph bars in the status bar itself (off: percentages only, bars on hover) |
usageHud.alignment |
left |
Which side of the status bar to sit on |
usageHud.pollSeconds |
60 |
Refresh interval in seconds (minimum 15) |
usageHud.floatMode |
window |
How the floating HUD opens: its own always-on-top window, or beside the editor |
Requirements
- VS Code 1.80.0 or higher.
- Claude Code, installed and logged in (the source of both the usage data and the per-window model).
- macOS or Linux for the usage windows (they read the login token from the OS credential store). The model and live-session features work from local files on any platform.
Install
From the Marketplace: search Claude Usage HUD in the Extensions view and click Install.
From a .vsix: Command Palette, Extensions: Install from VSIX, and pick the file.
How it works, in short
The extension never scrapes or polls aggressively. It reads the usage endpoint at most once a minute, caches the result in its own storage shared across windows, and reads local transcript files to know which model each window uses and which sessions are live. See docs/ARCHITECTURE.md for the full design.
License
MIT, see LICENSE.
