capgauge

A gas gauge for your AI coding limits.

Every other tool tells you what you already spent. capgauge tells you when you run out, and what is draining the tank.

npx capgauge

  capgauge  18420 real responses, last 21 days
  (37100 lines on disk, 18680 duplicates discarded)

  ██████████████████░░░░░░░░░░  63% of the weekly cap
  $412.00 spent this window, equivalent to a $654.00 cap
  ████████░░░░░░░░░░░░░░░░░░░░  29% of the 5 hour block, resets tuesday, 19:20

  You hit the wall around friday, 04:23
  from thursday, 16:26 in the fast case; in the slow one you make the reset

  What ate the week
      $131.00   32%  ~/code/api
       $88.00   21%  ~/code/web
       $54.00   13%  ~/notes

  Where it went
       $41.00   10%  model responses
       $99.00   24%  loading new context
      $272.00   66%  re-reading cached context

  Codex
  █░░░░░░░░░░░░░░░░░░░░░░░░░░░  2% of its weekly limit  (read 5 days ago)

Numbers above are illustrative. The percentages are not: that split between model responses and context reloading is what the tool actually finds on a heavy agent workload, and it is the reason "I barely used it" and "I hit the cap" are both true at the same time.

No setup, no API key, no account. It reads what your tools already wrote to disk.

The forecast

capgauge projects your current pace to the reset and tells you when the tank runs dry. It models the weekly limit as a fixed window, because that is what it is. On a rolling window a steady pace never hits the wall, so a rolling model shows a comfortable green right up until you are locked out.

It gives you a band, not a minute, and the band is measured on your data, not on someone else's. Every run backtests the production predictor against your own history and uses that error to size the band, which takes about 7ms. If you do not have enough history yet, it says so and falls back to a default.

capgauge backtest

cuts your history at points in the past, predicts forward using only what was known then, and compares against what actually happened. On the machine this was built on:

  horizon    n   hourly profile   7 day mean   yesterday   shape+level
    12 h    14             71%          58%         65%           70%
    24 h    14             42%          45%         57%           53%
    48 h    14             50%          39%         53%           48%
    72 h    14             48%          27%         49%           29%

The plain seven day mean wins, and it wins hardest at 72 hours, which is the distance that matters when you are aiming at a weekly reset. So that is what capgauge forecasts with.

This is worth saying plainly, because the first version of this tool did the opposite. It built an hourly profile of when you work and walked forward hour by hour, on the theory that if you never work Sundays it should not spend your Sundays. That story is convincing and it is wrong: an agent-heavy user is bursty, not weekly-periodic, and the profile overfits the noise. The profile survives in the report as a heatmap of when you actually work, which is genuinely interesting, but it does not get to predict anything.

Run capgauge backtest on your own data. If a different model wins for you, that is worth knowing, and the numbers above are one person's machine.

A sample is only counted if it has a full week of history behind it. Without that, the seven day mean is computed over less than seven days, comes out low, and the backtest reports a huge error that is the test's fault and not the model's.

Where the numbers come from

Your real percentage comes from your own account. Claude Code stores an OAuth token in ~/.claude/.credentials.json and reads api.anthropic.com/api/oauth/usage to draw /usage. capgauge reads the same token and calls the same endpoint, and no other: the host is fixed in the source, the token is never printed, never written to disk, never sent anywhere else. See src/live.mjs, it is about forty lines. Turn it off with --no-live and calibrate by hand instead:

capgauge calibrate --pct 63 --resets 2026-08-28T22:00 --tz America/Argentina/Buenos_Aires

The breakdown is computed locally from ~/.claude/projects. Subscription plans do not publish their cap in tokens, so capgauge prices every message at Anthropic first-party API rates and anchors that total to your real percentage. The dollar figures are an equivalence, not a bill.

Codex is read from ~/.codex/sessions, which embeds its own rate limit state, so that half needs no network at all. capgauge does not estimate dollars for Codex: there is no reliable price table for its models, and the percentage the harness reports itself is a better number than one we invented. That percentage only refreshes when you use Codex, so capgauge prints how old the reading is.

Counting honestly

Claude Code writes one line per content block and repeats the same usage object on each. Summing line by line roughly doubles the number. capgauge deduplicates by message.id and prints how many lines it discarded, so you can check the arithmetic against any other tool.

Cache writes are priced at 1.25x input for the 5 minute TTL and 2x for the 1 hour TTL, cache reads at 0.1x input.

Get warned before the wall

capgauge install-hook --at 70

Adds a UserPromptSubmit hook to ~/.claude/settings.json that prints a line once you cross the threshold. It caches the reading for five minutes, so it costs about 40ms on a normal prompt. Your previous settings file is copied to settings.json.capgauge-bak, and the installer refuses to write if the file changed while it was working, which happens when another session edits it at the same time.

Commands

| | | |---|---| | capgauge | status and forecast | | capgauge report [--out f] | full HTML report | | capgauge install-hook [--at N] | warn past N percent, default 70 | | capgauge calibrate --pct N | anchor the cap by hand | | capgauge --days N | analysis window, default 30 | | capgauge --no-live | never touch the network | | capgauge --no-codex | skip Codex transcripts |

Use at least --days 21 so the hourly profile has three weeks to learn from.

Tests

npm test

60 tests on node:test, no dependencies. They cover the claims that would make the tool lie if they broke: deduplication by message.id, the fixed window against a rolling one, the forecast band ordering, the cache write and read multipliers, the Codex rate limit reading surviving a later null, timezone translation, the hook never throwing or leaking a token, and the fast range-sum agreeing with the plain scan on every boundary.

MIT.