DEV Community: Rehber Odhano

Claude usage jumped? How I added project, session and subagent attribution to my usage tracker

Rehber Odhano — Tue, 13 Oct 2026 17:28:52 +0000

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):

https://dev.to/rehberodhano/predicting-when-youll-hit-your-claude-usage-limit-without-scraping-the-page-1llh

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.

How I Predict Claude Usage Limits Without Scraping the Page

Rehber Odhano — Sun, 27 Sep 2026 21:45:14 +0000

A usage percentage tells you where you are. It doesn't tell you whether you're in trouble.

What I actually wanted to know was this:

At my current pace, am I going to hit the limit before it resets?

62% an hour into a window and 62% shortly before the reset are very different situations, and Claude only shows you the number. So I built Claude Usage Companion, an open-source, local-first browser extension that adds the missing context.

It's at v0.3.2 now, but the engineering problem hasn't changed: how do you turn usage snapshots into something you can act on, without scraping Claude's UI or sending your data to yet another backend? This post is about how I approached that.

The percentage wasn't enough

Claude's paid plans have two limits: a 5-hour session window and a 7-day weekly window. Both show up as percentages under Settings → Usage.

On its own, a percentage doesn't say much. Compare these two:

Situation A                          Situation B
Session usage:    62%                Session usage:    62%
Time into window: 1 hour             Time into window: 4 hours 30 minutes
Time until reset: 4 hours            Time until reset: 30 minutes

In A you've burned a large share of the allowance very early, and if that pace holds you'll hit the limit long before the reset. In B the number is identical, but you're almost at the reset and probably fine.

So instead of just "Session usage: 62%", I wanted the extension to say something like this, and only when it's true:

At this pace, session runs out ~Thu 3:40 PM — before it resets.

The percentage tells you where you are. The pace tells you whether to care.

Why I didn't scrape the page

The obvious way to build this is to open the usage page, find the percentage in the DOM, parse the text, and save it. It works until a CSS class changes or a component gets redesigned, and then the extension quietly breaks.

The network responses behind the page are a steadier thing to build on, so the extension watches the responses claude.ai already receives. Three of them matter:

/usage, from a background poll or from the page's own request
the message_limit event at the end of a chat reply's stream
rate_limit_event entries from Claude Code on the web

Here's the whole path, from those three sources to what you see:

  GET /usage ──────────────────┐
  poll, or the page's own call │
                               │     ┌───────────────────────────────┐
  message_limit ───────────────┼───► │ background service worker     │
  end of a chat reply          │     │                               │
                               │     │  1. validate    (zod)         │
  rate_limit_event ────────────┘     │  2. normalize                 │
  Claude Code on the web             │  3. store       (IndexedDB)   │
                                     │  4. forecast                  │
                                     │  5. alert, badge, popup       │
                                     └───────────────────────────────┘

The page hook only observes. Claude gets its original response, untouched. The background poll is separate: every 5 minutes an alarm requests /usage using your existing claude.ai session. claude.ai's own frontend only asks for that endpoint when you open Settings → Usage, and I didn't want the bars going stale in between.

Chrome's isolated world makes this awkward

Chrome content scripts run in an isolated JavaScript environment. That's good for security, but it means a normal content script can't replace the page's window.fetch. To watch Claude's network calls I need two small scripts:

 claude.ai tab
┌───────────────────────────────────────────────────────┐
│                                                       │
│  MAIN world (the page's own realm)                    │
│  ┌─────────────────────────────────────────────────┐  │
│  │ hook                                            │  │
│  │  · wraps window.fetch                           │  │
│  │  · reads a clone, the page gets the original    │  │
│  │  · drops everything except usage events         │  │
│  └───────────────────────┬─────────────────────────┘  │
│                          │ window.postMessage         │
│  ISOLATED world          ▼                            │
│  ┌─────────────────────────────────────────────────┐  │
│  │ relay                                           │  │
│  │  · has browser.runtime access                   │  │
│  │  · passes payloads along, no parsing            │  │
│  └───────────────────────┬─────────────────────────┘  │
│                          │                            │
└──────────────────────────┼────────────────────────────┘
                           │ runtime message
                           ▼
                background service worker

The hook is small on purpose, and it has one rule: a bug in my extension must never break claude.ai. Simplified, it looks like this:

const originalFetch = window.fetch.bind(window);

window.fetch = async (...args) => {
  const response = await originalFetch(...args);

  try {
    void handleResponse(
      response.clone(),
      getRequestUrl(args[0])
    );
  } catch {
    // Losing a usage sample is acceptable.
    // Breaking Claude is not.
  }

  return response;
};

Note the response.clone(). The page gets the original, and the extension reads the copy.

Some of the data arrives inside a stream

Chat replies are streamed, and the message_limit event I want is buried near the end of that stream. So it isn't a simple await response.json(). The body is a ReadableStream, and the extension has to read chunks and rebuild complete SSE frames from them:

const reader = response.body?.getReader();

if (!reader) {
  return;
}

const frames = new SseFrameBuffer();

for (;;) {
  const { done, value } = await reader.read();

  if (value) {
    for (const frame of frames.push(value)) {
      handleFrame(frame);
    }
  }

  if (done) {
    for (const frame of frames.flush()) {
      handleFrame(frame);
    }

    break;
  }
}

The buffer matters because network chunks don't respect message boundaries. One SSE event can be split across two chunks, or several can arrive in one, so parsing line by line straight off each chunk isn't reliable.

Throwing away what I don't need

Some of these responses carry far more than usage data, and I decided early that being able to see something isn't a reason to keep it.

Claude Code on the web is the clearest case. Its events endpoint returns user and assistant entries alongside the rate_limit_event entries I'm after. The filter runs inside the page's own context, before postMessage fires, so conversation text never reaches the extension at all, not even briefly. The chat stream gets the same treatment: only message_limit frames are forwarded, and the rest is ignored.

I don't want this to become a conversation recorder. Keeping that boundary narrow also makes the privacy story easy to explain.

Treating undocumented data as unstable

None of this was designed as a public API, so I assume it can change under me. Fields appear and disappear, objects turn into null, new keys show up. Every payload goes through runtime validation before anything is stored:

const result = UsageSchema.safeParse(payload);

if (!result.success) {
  logValidationFailure(result.error);
  return;
}

const normalized = normalizeUsage(result.data);

store(normalized);

(Those names are illustrative, not the real identifiers.) A few rules came out of this:

Unknown fields don't invalidate a payload. A new key in Claude's response isn't a reason to throw it away.
Optional means optional. If I haven't seen a field in every capture, nothing depends on it being there.
Bad input gets skipped, not guessed at. I'd rather show nothing than a confident wrong number.

Defensive parsing makes the integration more resilient. It doesn't turn an undocumented interface into a stable one, and if the format changes enough, the extension will go quiet until I ship a fix.

The forecast is boring math

Once I had a history of snapshots, I needed to estimate where the current run was heading. I thought about something fancier and decided against it. The forecast fits a straight line (ordinary least squares) through recent samples and solves for where it reaches 100%:

 100% │                                 ·
      │                              ·
  80% │                           ·
      │                     ·  ·
  60% │                  ·
      │               ·
  40% │         ●  ●
      │      ●
  20% │   ●
      │●
   0% │
      └──────────────────────────────────────▶ time

The filled dots are real samples, and the small dots are the line projected forward until it hits the top.

Resets break a naive fit

Windows reset, and when they do the percentage falls back toward zero. A history might look like 72%, 79%, 86%, then 4%, 10%, 18%. A single line fitted across the whole history would be nonsense, because the reset breaks it in the middle. The fit has to start after the drop, and the projection should come only from the new run:

 100% │        ┊                                          ·
      │      ● ┊                                       ·
  80% │   ●    ┊                                    ·
      │●       ┊                              ·  ·
  60% │        ┊                           ·
      │        ┊                     ·  ·
  40% │        ┊                  ·
      │        ┊               ·
  20% │        ┊         ●  ·
      │        ┊      ●
   0% │        ┊   ●
      └────────────────────────────────────────────────────────▶ time
               reset

So only the current run counts. Starting from the newest sample, walk backward until the percentage drops:

let runStart = sorted.length - 1;

for (let i = sorted.length - 1; i > 0; i--) {
  if (sorted[i].percent < sorted[i - 1].percent) {
    break;
  }

  runStart = i - 1;
}

const currentRun = sorted.slice(runStart);

if (currentRun.length < 2) {
  return null;
}

That way the fit only sees samples from the current window. (In the real code this splitting rule lives in one shared helper, because anomaly detection needs the same reset boundaries.)

Why not something smarter?

Because real usage is lumpy. You prompt hard for twenty minutes, read code for forty, sit in a meeting, then start a big session. Nothing inside the extension knows what you'll do thirty minutes from now, and a fancier model would mostly add the look of precision without knowing any more.

That's why the wording is always "at your recent pace". The forecast doesn't predict what you'll do, it extrapolates what you've already been doing.

Confidence over precision

A forecast built on two samples shouldn't look as trustworthy as one built on a longer history, so every forecast carries a deliberately cheap confidence label:

low: fewer than 3 samples in the current run
medium: 3 or more samples
high: 5 or more samples spanning at least an hour

It's a rough proxy for how much to trust the line, not a statistical confidence interval. It's also why I never show "You WILL run out at exactly 3:47 PM". Something like "session runs out ~Thu 3:40 PM — before it resets" gives you what you need to make a call without pretending to know the future.

Knowing when to stay quiet

This ended up mattering as much as the math. If an extension warns you all the time, you stop reading the warnings, so a forecast shouldn't automatically become an alert. The popup headline and the opt-in pace notification only fire when all three of these hold:

the bar is at least 10% used (a forecast of "limit in 141 hours" at 3% used is noise)
the forecast has medium or high confidence
the projected run-out lands at least 30 minutes before the window resets

So a projection of 4:58 PM against a 5:00 PM reset gets no drama, since that's effectively fine. A projection of 2:40 PM against the same reset does.

Sustainable pace

Forecasting asks when you'll hit the limit at your recent pace. There's a second useful question: how fast can you use what's left and still make it to the reset?

Say you have 66% remaining and 5 hours until reset. This one isn't a forecast, it's plain arithmetic on two numbers Claude reports:

(100 − percent used) ÷ hours until reset

Here that's 66 ÷ 5 ≈ 13% per hour, the rate at which you'd use up the remaining allowance exactly as the window resets. The extension compares it with your recent pace, but only when the forecast is medium or high confidence:

Recent pace:       high
Sustainable pace:  lower

You don't need to read a chart to see that you're burning faster than you can afford. This is part of the current version as well.

Account usage and local Claude Code activity aren't the same data

The browser can see account-level usage. People also asked what they were doing in Claude Code that was contributing to it, and a browser extension can't look inside your terminal. Claude Code does keep session data locally, though, so Claude Usage Companion has an optional local daemon that reads it:

 your browser                             your machine
┌──────────────────────────┐            ┌─────────────────────────────┐
│ extension                │  HTTP to   │ daemon (Node + Hono)        │
│  · usage history         │  127.0.0.1 │  · reads Claude Code's      │
│  · forecasts, dashboard  │ ─────────► │    session logs             │
│                          │  + token   │  · shells out to            │
│                          │ ◄───────── │    ccusage --offline        │
└────────────▲─────────────┘            └──────────────┬──────────────┘
             │ network capture                         │ read-only
             │                                         ▼
         claude.ai                      ~/.claude/projects/**/*.jsonl

The daemon can derive projects, models, sessions, token activity and subagent activity. What it can't do is tell you how that activity relates to your account totals, and I don't want the UI to imply otherwise.

Correlation isn't causation

Suppose weekly usage jumps, and around the same time the daemon sees a big local Claude Code session. It's tempting to blame the session. But you may also have used claude.ai in the browser, used Claude somewhere else, switched models, or generated more output in that window. The data supports "this local activity happened then", not "this caused the jump".

So the UI treats three kinds of values differently:

Reported by Claude    session usage, weekly usage, reset times
Observed locally      Claude Code projects, models, sessions, subagents, token activity
Derived               forecast, sustainable pace, anomaly detection, contribution estimates

They don't have the same provenance, so they shouldn't look like they do.

Localhost isn't automatically private

It's easy to assume that anything on 127.0.0.1 is private, but any website you open can try to send requests to services listening on localhost. So the daemon doesn't lean on the loopback address alone. Every request has to get past a few checks, in this order:

 request                                             result
 ─────────────────────────────────────────────────   ───────────────────────
 a website (http/https origin), even with a token    403 forbidden_origin
 anyone, no token                                    401 unauthorized
 your extension + token                              ok
 curl or the statusline script (no Origin) + token   ok

The full list of protections:

binds to 127.0.0.1 only
a bearer token on every route, compared in constant time, with the token file readable only by you
any http(s) page origin rejected outright, even with a valid token
no unauthenticated routes except /health and the one-time /pair
no conversation content in logs

Pairing means you never copy a token by hand. The extension asks the daemon for its token once, right after install, and the daemon then locks that endpoint, so every later request is refused. (If you reinstall the extension, run claude-usage-daemon install again to open a fresh pairing window.)

I kept the daemon narrow. It's stateless: your history lives in the extension's local storage, and the daemon only writes its own token file, a pairing marker, and its background-service registration. It never writes into your projects, and I don't want it to grow into a general-purpose local API server. Features like session search and export do read session content, but only locally and on demand, and nothing is sent anywhere.

The privacy model is boring on purpose

There's no Headroom backend between you and Claude, no telemetry, no product account, and no analytics service receiving your history. The browser side works with Claude data your signed-in session can already see, and the optional daemon works with files on your own machine. Everything it stores stays local. For a tool that watches your usage, I think boring infrastructure is a feature.

What it has become

Early versions already showed the limit bars and a burn-rate forecast. The current version tries to answer more questions:

Where am I now?
Am I likely to hit the limit before reset?
Is my current pace sustainable?
Is this usage pattern unusual?
What changed recently?
Which Claude Code projects and models were active?
Which sessions and subagents ran?
Can I find and resume an older Claude Code session?

That deserves its own article, so I'm not turning this one into a v0.3.2 changelog. This post is about the foundation those features sit on.

The stack

It's a TypeScript monorepo:

packages/
├── shared/      schemas and shared usage models
├── extension/   WXT + React + IndexedDB
└── daemon/      Node.js + Hono

The extension handles capture, local history, forecasting, alerts and the dashboard. The daemon is optional and only handles local Claude Code visibility. Both live in the same open-source repo.

Try it

Chrome / Edge: Claude Usage Companion 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 (the repo explains how). After installing, open claude.ai's Settings → Usage page once, or just send a message, so the extension can detect your account. From then on it keeps itself up to date in the background. You'll need an active Claude plan with usage limits, because free accounts have no usage page to read.

Source code (MIT): https://github.com/RehberOdhano/headroom

Optional Claude Code daemon (needs Node.js 20 or later):

npm install -g @rehberodhano/claude-usage-companion-daemon
claude-usage-daemon install

The extension works fine without the daemon. Install it only if you want the local Claude Code features.

What I'd like to hear

This started because I wanted a better answer than "62% used". I wanted to know whether I was actually in danger of hitting the limit before the reset. That question led to forecasting, sustainable pace, anomaly detection, Claude Code attribution, session tools, and a fair number of rabbit holes.

I don't want it to turn into a dashboard full of numbers just because they can be calculated. So if you use Claude regularly:

What's the one piece of usage information you wish Claude showed you directly?

Feedback, bug reports and feature ideas are all welcome on GitHub.