The first version of Claude Usage Companion covered the limit bars, a burn-rate forecast, and basic project and model attribution from Claude Code. That told me where I stood. It didn't tell me why.
What kept happening was this: I'd open Settings → Usage and the weekly bar had jumped. Was it yesterday's refactor? One long Claude Code session? Did a model dominate the week? Did a subagent run much longer than I expected? Or was this just a normal week and I'd forgotten?
Claude gives you the percentage, not the why. So I kept building. It's at v0.3.2 now, still with no backend, no telemetry and no account. Everything stays on your machine.
(If you want the engineering side, how it captures usage without scraping the page and how the forecast works, I wrote that up in the first article. This one is about what the product does now.)
Three places, three questions
The popup stays small on purpose. It shows the Session (5h) and Weekly bars, and says something only when something needs attention: a limit you've already hit, or a forecast that runs out early, like
At this pace, session runs out ~Thu, 3:40 PM — before it resets.
If a bar is rising unusually fast it adds a separate line:
Session usage is rising faster than its recent pattern.
The full dashboard has three tabs:
- Overview: am I on track?
- Activity: what changed, and where is the usage going?
- Sessions: find, resume, export and keep old Claude Code sessions
Activity needs the optional daemon for its content, and Sessions only appears once the daemon is connected. Overview works without it.
Overview: am I on track?
Besides the bars, reset times and history, Overview has the forecast, which fits a line through your current usage window and says when it would hit 100%. The dashboard version also tells you how much earlier than the reset that is:
At current pace, reaches limit ~Thu, 5:32 AM — that's 3h 20m before reset.
Switching to a lighter model or pacing back would stretch it.
The dashboard line shows up for any bar that's at least 10% used and tags a thin forecast as "(low confidence)". The popup headline and the optional pace notification are stricter: they need medium or high confidence and a projection that lands at least 30 minutes before the reset. A warning that fires all the time gets ignored.
Sustainable pace
A forecast says where your recent pace leads. The other useful question is how fast you can go and still make it to the reset. That's plain arithmetic on two numbers Claude reports: what's left, divided by the hours until reset. With 66% left and 5 hours to go:
Average usage should stay around 13.2%/hour or lower to last until reset.
Your recent pace is about 40% above that.
The second sentence only shows up when the forecast is at least medium confidence, and it's rounded to the nearest 5%, because a fitted rate shouldn't pretend to single-percent precision.
Anomaly detection
Sometimes the useful signal isn't a forecast, it's "this is climbing much faster than it usually does." The extension compares your current run with your own recent windows: it flags a bar when its current rate is at least twice the median rate of your last few completed windows. It needs a couple of finished windows before it says anything, it stays quiet right before a reset, and it labels itself "early pattern — based on limited history" while the baseline is thin.
The wording describes behavior, never a cause. A change on Anthropic's side can move the observed rate as much as your own usage can.
Usage Inspector: what was running when it spiked?
When an anomaly fires on Overview, there's an inspector under it. It looks at the local Claude Code sessions active during that window and shows the largest local project with its share, the model mix, and the biggest sessions:
Largest local contributor observed during this period:
storefront-api (62% of observed local activity).
(storefront-api is a made-up name.) Sometimes nothing matches, and then it says so instead of inventing an explanation:
Headroom did not observe local Claude Code activity matching this increase.
Usage from claude.ai or other unobserved sources may have contributed.
That caveat is the point. The browser sees your account-level usage, and the daemon sees local Claude Code activity. They overlap, but they aren't the same data, since you may also use claude.ai, another machine, or another tool. So the inspector says "observed during this period", never "caused by".
Activity: where is it going?
With the daemon connected, Activity breaks Claude Code usage down by project, model and session. There's also a rough "~N% of this week" estimate per project, and I'll repeat the caveat from the UI: the estimate treats all weekly movement as CLI-caused, so it leans high if you also use claude.ai in the same period.
The What changed section compares this week with the same elapsed portion of last week, and only appears when a difference is big enough to matter. If nothing is, the section isn't there at all. What it can say looks like this:
Project storefront-api share increased from 18% to 27% compared with
the same elapsed portion of the previous window.
CLI volume Observed CLI tokens up 35% compared with the same elapsed
portion of the previous window.
Subagents
Expand a session and you can see which subagents ran inside it, each with its type, description, model and its own token total. Those totals are shown separately and never added to the session's number. When I looked at real local data, I couldn't tell whether the existing session totals already include subagent activity, and I didn't want to guess at the accounting and show an incorrect sum. A separate, honest number is less tidy than one big total, but it's less likely to be wrong.
Sessions: don't lose the good ones
Claude Code keeps session history locally, and by default it cleans old sessions up after 30 days. Since the daemon was already reading those files, a few things became easy:
- full-text search across past sessions
- a copy button for the resume command:
cd /path/to/project && claude --resume <session-id> - Markdown export (images included, and an opt-in for short summaries of tool calls)
- a warning, plus a count on the toolbar icon, for sessions nearing the cleanup
I wanted to know a session was about to disappear before it did.
Smaller things that turned out to matter
Statusline. The npm package includes a script for Claude Code's statusLine setting. It prints something like this:
Session: 34% (resets in 2h 10m) | Weekly: 22% (resets in 76h 10m) | Today: 1.8M Tokens
Session and weekly come from Claude Code's own input (Pro/Max, after your first message in a session), so they work without the daemon. The token total needs it.
Backup and restore. Usage history lives in the browser, so clearing site data would wipe weeks of it. Settings can export history and settings to a file and restore them later. The daemon connection is deliberately left out of the backup, and a restore only adds snapshots you don't already have.
Diagnostics. I didn't want to ask anyone to "send me your logs" from a tool that runs next to private conversations. Settings → Diagnostics produces a short summary you can copy: versions, last capture, whether the daemon is reachable, and project and session counts. It never includes your token, account id, or conversation content.
What needs the daemon, and what doesn't
The extension on its own handles the bars, history, forecast, sustainable pace and anomaly detection. The daemon is for everything that depends on local Claude Code data: project, model, session and subagent attribution, What changed, the Usage Inspector, session search, resume, export, retention warnings, and the statusline's token total.
npm install -g @rehberodhano/claude-usage-companion-daemon
claude-usage-daemon install
It's optional, binds to 127.0.0.1 only, requires a token, rejects requests from regular web pages, and never uploads anything. You'll need an active Claude plan with usage limits, since free accounts have no usage page to read.
Try it
Chrome / Edge: the extension is on the Chrome Web Store (Edge can install the same listing):
https://chromewebstore.google.com/detail/chjbjdabpficejgogljohhlobfaehepl
Firefox isn't on a store yet, so it has to be built from source. After installing, open Settings → Usage on claude.ai once, or just send a message, so the extension can find your account.
Source code (MIT):
https://github.com/RehberOdhano/headroom
Optional Claude Code daemon (Node.js 20 or later), also on npm:
https://www.npmjs.com/package/@rehberodhano/claude-usage-companion-daemon
npm install -g @rehberodhano/claude-usage-companion-daemon
claude-usage-daemon install
How it works under the hood (network capture, the forecast, localhost security):
What I'd like to hear
I'm trying not to add a metric just because I can calculate it. So when your usage spikes, what do you want to know first: which project, which model, which session, whether a subagent was involved, or something else? Bug reports and ideas are welcome on GitHub.
Top comments (0)