Most usage tools for Claude Code show you the numbers. This one shows them to Claude, before every prompt, and changes what it does about them.
Claude Code already knows how much of your 5-hour and weekly limit is gone. It caches those numbers locally and will show them if you ask. What it does not do is notice that the job in front of it is larger than the budget behind it. So it starts anyway, and stops halfway through an edit.
This puts the budget in front of Claude before your prompt lands, so the reply opens with the answer instead:
The weekly window has about 22 turns left. That covers the parser change and its tests, but not the migration or the docs pass, so I will do the first two and leave the rest for after the reset at 09:00.
Nobody read a chart to get that. The numbers reached the model, not you.
There are a lot of good tools that read the same local files this does and draw you a picture: status lines, menu bar apps, terminal dashboards. They are worth having, and this is not trying to replace them. The difference is who the output is for.
| A usage dashboard | This |
|---|---|
| Renders numbers for a person to read | Puts numbers in the model's context |
| You notice, then you interrupt | Claude notices, and adjusts on its own |
| Tells you 78 percent is gone | Tells you 22 turns are left, and whether what you asked for fits in them |
| Runs beside Claude Code | Runs inside it, as a skill and a hook |
| Shows what already happened | Says what to do now, and what to drop |
A percentage is a fact about the past. The useful question is whether the thing you just asked for is going to finish, and answering that needs the request and the budget in the same place. That place is the model's context, which is where this puts them.
So: if you want to watch your usage, install a status line. This ships one too, and a live panel that sits beside the chat, both drawn in Claude Code's own colours from Claude Code's own numbers. If you want the thing spending the budget to know it is spending the budget, that is what this is for.
Claude Code usage
Plan Claude Pro
Snapshot 3m old
Settings model=opus effort=xhigh
Overage off, work stops at the limit
Window Used Resets in Left Turns left
5-hour 62% 1h 40m $46.00 ~88 <- binding
weekly 75% 2d 4h $124 ~240
Recent pace 15 turns in the last hour, $0.164 per turn, effort xhigh
Measured 1,284 turns of local transcript
The 5-hour limit is the binding one. At the current pace it runs out in about
1h 12m, which is 28m short of the reset. Size the work to fit, or slow the burn.
Turns left is the column that matters. It divides the remaining headroom by
what a turn has actually been costing over the last hour, on your account, at
your effort level, so it moves when your working style does. Fifteen turns of
headroom means something you can plan against; 75 percent does not.
It also breaks the window down by model, with the token split behind it:
Models in the 5-hour window
Model Turns Tokens Output Share
claude-opus-5 159 27.0M 212k 100%
Tokens input 318, cache write 631k, cache read 26.2M, output 212k
When more than one project has run inside the window it breaks that down too, so you can see which working directory actually spent the week:
Projects in the weekly window
Project Turns Tokens Share
...ideLink-Stuff-app 930 45.2M 78%
C--Users-OWNER 240 12.1M 22%
That split is usually the surprise. Almost all of it is cache reads, billed at a tenth of the input rate but paid again on every turn, which is why context length matters more than any single expensive message.
The percentages and reset times come from Claude Code's own cache. The pace comes from your local session transcripts. Neither requires a network call.
Nothing to install, if you just want the numbers:
npx claude-usage-limits
npx claude-usage-limits --status
npx claude-usage-limits lowpower on
That runs the same code as the plugin, from claude-usage-limits on npm. Node 18 or newer.
To have Claude read the numbers and plan against them, install it properly.
As a plugin:
/plugin marketplace add ridelink0/claude-code-usage-limits
/plugin install usage-limits@usage-limits
As a plain skill, if you would rather not use the plugin system:
git clone https://github.com/ridelink0/claude-code-usage-limits
cp -r claude-code-usage-limits/skills/usage-limits ~/.claude/skills/usage-limits
On Windows, in PowerShell:
git clone https://github.com/ridelink0/claude-code-usage-limits
Copy-Item -Recurse claude-code-usage-limits\skills\usage-limits "$env:USERPROFILE\.claude\skills\usage-limits"
One difference between the two: the hook that puts the budget line in front of
every prompt is declared in the plugin manifest, so it only runs on a plugin
install. If you took the plain skill and want that behaviour, add it yourself
in ~/.claude/settings.json, pointing at wherever you put the skill:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "node \"$HOME/.claude/skills/usage-limits/scripts/brief.js\"",
"timeout": 10
}
]
}
]
}
}Either way, ask something like "how much usage do I have left" or "can we
finish this before the limit hits" and Claude will load it. Installed as a
plugin it also gives you /usage-limits:check, which prints the report and
sizes whatever you just asked for against it.
The scripts also run on their own, with or without any of the above:
node skills/usage-limits/scripts/usage.js
node skills/usage-limits/scripts/usage.js --json
Two Claude Code windows share one limit, so headroom measured in turns is optimistic while another session is also spending. It watches for that:
Sharing 2 sessions have spent in the last 15m, splitting this budget 75% / 25%
The turns above are the whole window, not your slice of it.
and the before-prompt line says how many of those turns are actually yours:
about 38 turns of headroom (2 sessions active, roughly 10 of them yours)
The split comes from measured spend rather than an assumption that everyone is working equally hard, because they usually are not. A session that has gone quiet for a quarter of an hour is not counted as competing.
Every session's spend also feeds the reading itself, not just the split. The percentage is corrected using all spend recorded since the snapshot was taken, whichever window produced it, so another Claude burning budget in the next terminal moves your number too.
Two windows run at once and the 5-hour one is usually what actually stops you, so it gets picked whenever it is tighter, and it wins a tie against the weekly window because the shorter window is the one hit first in practice.
It is not forced, though. When the weekly window is genuinely the wall, at 99 percent with minutes left, that is what gets reported. Forcing the 5-hour there would hide the limit about to stop the work, which is the same failure as ignoring it.
A window with no recent spend to measure is ranked by how full it is rather than being skipped, so a 5-hour window sitting at 95 percent is never passed over just because nothing has gone through it in the last few minutes.
Binding is about what stops you soonest, though, not what stopping costs, and those are different: a 5-hour window returns in hours, the weekly one in days. So a window above 85 percent gets called out even when something shorter binds, with its own reset time, because spending the weekly window to save a few turns of the 5-hour one is a bad trade.
Every message sent while work is already running starts another turn, and each turn re-sends the whole conversation. Three follow-ups during one task can cost more than the task did.
So when several additions arrive mid-task and the binding window is tight, Claude says so once and keeps working:
I have got all three. While the weekly window is this tight, sending them together costs a good deal less than one at a time, so I will fold these in and carry on.
It asks once, never repeatedly, and only when the budget is actually tight. Asking someone to hold their thoughts when there is room to spare is rude for no gain.
The important exclusion: it never discourages a correction, a stop, or a bug report. Those are the messages that save the most work, and a rule that trains people out of interrupting to say "that is wrong" costs far more than the turns it saves. Only additive scope is worth batching.
The report says which of two things happens when the plan allowance runs out, because they need opposite handling.
If paid credits are off, work stops dead and there is no buying through it, so the report says so and plans around it. If they are on, the limit is a cost boundary instead of a wall. It deliberately does not warn you about that crossover, because Claude Code already announces it and asks before drawing on credits, and a second warning saying the same thing is just noise.
When the binding window will run out before it resets, the report stops describing and starts instructing:
The 5-hour limit is the binding one. At the current pace it runs out in about
20m, which is 3h 40m short of the reset. Size the work to fit, or slow the burn.
Work stops when it does. Nothing carries on into paid credits.
Land what exists, write the handoff, and resume after 03:00.
The clock time matters more than the countdown. "Resume after 03:00" is a plan; "4h 12m" is a number you still have to do arithmetic on.
The skill also requires Claude to say up front when a job will not fit in what is left, name what it is doing now, what it is leaving, and when the rest can happen, rather than starting and stopping halfway through an edit.
npm version patch
git push --follow-tags
Pushing the tag runs the tests and publishes to npm. That goes through npm's
trusted publishing over OIDC, so there is no publish token stored in the repo
or in CI. npm version also syncs the version in the plugin manifest, so the
marketplace and the npm package never disagree about which release is current.
npx claude-usage-limits panel --open
That opens a narrow pane to the right of the one Claude Code is running in (Windows Terminal, tmux, WezTerm, kitty, zellij and iTerm2 are all understood) and draws the limits in it, live:
✻ Claude usage
Fable 5.1 · xhigh · working
Current session
███████░░░░░░░░░░░░░░░░░░░░░ 24%
resets in 4h 12m at 6:40 PM
Current week (all models)
█░░░░░░░░░░░░░░░░░░░░░░░░░░░ 4%
resets in 1d 5h at Sun 7:00 PM
Current week (Fable)
█░░░░░░░░░░░░░░░░░░░░░░░░░░░ 3%
resets in 1d 5h at Sun 7:00 PM
Sessions · 1 working, 1 idle
✳ Fable 5.1 usage-limits working
· Opus 5 ridelink idle 4m ago
live, updated 12s ago
q quit · r refresh
Four things about it are deliberate.
It is drawn the way Claude Code draws things. The colours are Claude
Code's own theme, read out of the CLI rather than approximated: the bar is the
one /usage paints, the title is the Claude orange, the spinner is Claude's
spinner with Claude's frames. A bar turns yellow at 80 percent and red at 90,
each window judged on its own. While Claude is working the title shimmers and
the spinner turns; while it waits, they stop. Under ultracode both go rainbow,
which is what Claude Code does with its max effort tag.
The numbers are the ones Claude Code uses. Every reading is the same GET
that /usage makes, with the login Claude Code already holds, plus the
rate-limit headers on Claude's own API responses whenever the status line
below is installed. Whichever is newer wins, and the footer says how old it
is. The week for one model (the Fable line above) only appears while that
model is the one running, because it cannot stop work on any other; when the
model cannot be told at all, nothing is hidden on a guess. The
reading is kept in usage-limits-live.json, and the report, the hooks and the
status line all prefer it whenever it is newer than Claude Code's own cache,
which can sit hours behind.
It keeps drawing when things go wrong. Offline, it shows the last reading and says how old it is, and tries again at a widening interval. Signed out, it says so in red and keeps checking, because Claude Code refreshes the login on its own next call. Told to slow down by the endpoint, it waits exactly as long as it was told. Too narrow a pane loses the breathing room, then the footer, never the bars. Nothing in it refreshes or rotates the token, and the token is never written anywhere by this plugin.
It knows about the other Claudes. Two windows share one limit, so the
panel lists every session this machine has heard from in the last quarter of
an hour: what it runs, where, and whether it is working right now, each with
its own spinner. The hooks are what say so (a prompt marks a session working,
every tool call keeps it so, the Stop hook marks it idle), so the list is live
without anyone polling anything. The status line adds +1 working when
another session is spending.
panel alone runs it in the current pane, --once prints one frame, --json
prints the fields, --no-fetch (or USAGE_LIMITS_FETCH=off) keeps it
entirely offline on the reading already on disk, and --poll N sets the
seconds between readings (30 while Claude works and 120 while it waits
otherwise). Installed as a plugin, /usage-limits:panel opens it from inside
the chat.
Not on the desktop app or claude.ai, which show the limits themselves. This is
for the terminal and the VS Code extension, where the only way to see them is
to ask with /usage.
The same bars, one line under the prompt:
✻ Fable 5.1 · xhigh session ████░░░░░░ 42% week █░░░░░░░░░ 7% fable █░░░░░░░░░ 3% +1 working
npx claude-usage-limits statusline on
npx claude-usage-limits statusline off
on points Claude Code's statusLine setting at a small launcher in the
config directory that finds wherever the plugin is currently installed, so a
plugin update does not leave the status line pointing at a folder that has
gone. A status line that was already there is kept and printed above ours;
--no-chain replaces it instead, and off restores exactly what was there,
including nothing. --refresh N re-runs it every N seconds as well as on every
change, which keeps the spinner turning between responses at the cost of a
Node process every N seconds. The change applies to new sessions.
The line is also where the panel learns what Claude is doing. Claude Code
hands the status line the model in use, the effort level, and the rate limits
from its own response headers, and the line records them for the panel, which
never sees that JSON. It reads no transcripts and makes no network calls, so it
costs about a tenth of a second on every redraw. It shrinks to fit narrow
windows, honours NO_COLOR and Claude Code's prefersReducedMotion, and
prints nothing rather than an error if anything goes wrong.
The older one-line form is still there as usage.js --status, which prints
5h 62% 1h 40m wk 75% 2d 4h and prefixes LOW past 90 percent.
Installed as a plugin, a hook measures the budget before each prompt and puts one line into Claude's context:
[usage-limits] binding window is 5-hour 47% used, about 75 turns of headroom,
resets in 3h 52m. Other windows: weekly 16%. This session: 229 turns, 14.2M tokens, $64.16.
It names the window that will stop the work first and hangs the figures off that one. Two windows run at once and they are rarely in the same place, so "weekly 16%" sitting next to "75 turns" would read as far more room than exists.
Claude opens with it. When there is room that is a single line and it moves on:
The 5-hour window is the binding one: 47% used, about 75 turns of headroom. This fits easily.
When there is not, the line becomes a plan rather than a status:
The weekly window has about 22 turns left. That covers the parser change and its tests, but not the migration or the docs pass, so I will do the first two and leave the rest for after the reset at 09:00.
The wording changes with the pressure, not only the numbers. The trigger worth explaining is pace: two days into a week you should be near 29 percent spent, so 60 percent means you will not last the week, and that is worth hearing at 60 rather than at 85.
The percentages behind the line are kept fresh too. If the reading on disk is
older than three minutes when a prompt goes in, the hook first takes the same
reading Claude Code takes for /usage, and the mid-turn pulse does the same
every two minutes through a long turn. That is what stops a burst of parallel
agents from emptying a window between two readings: eight of them once spent
half a window in five minutes while the line, seventeen minutes old, still
said 42 percent. Offline that is one quick failure and then a widening
backoff, never a wait on every prompt.
One limit worth knowing: the hook fires when a prompt is submitted, so a message sent while Claude is already working does not refresh it. Claude Code delivers those into the running turn without re-running hooks, which no plugin can intercept. The skill handles it by telling Claude the figures age during a turn, and to re-read them before claiming a job fits rather than trusting a number from several tool calls ago.
It has to be cheap, because it runs on every prompt. The percentages come from one small file. The transcript scan behind "turns of headroom" is cached for a minute, so it costs about 400ms cold and 120ms warm.
| Variable | Default | Effect |
|---|---|---|
USAGE_LIMITS_BRIEF |
on | Set to off to turn the before-prompt line off entirely. |
USAGE_LIMITS_NEAR |
90 | Percent used at which the budget counts as tight. Nothing below it is discouraged. |
USAGE_LIMITS_FEW_TURNS |
10 | Turns of headroom at or below which the budget counts as tight. |
USAGE_LIMITS_RUNWAY |
10 | Minutes of runway at the current pace below which the budget counts as tight. |
USAGE_LIMITS_CACHE |
60 | Seconds the measured half stays good for. |
USAGE_LIMITS_FLOOR, USAGE_LIMITS_AHEAD |
40, 15 | Only feed the reported pace figure; they no longer change the wording. |
USAGE_LIMITS_PULSE |
on | off silences the mid-turn line; always prints it even when there is room. |
USAGE_LIMITS_PULSE_SECONDS |
120 | How often the mid-turn line can fire. |
USAGE_LIMITS_TALLY |
on | Set to off to turn off the after-reply tally, the closing line and the session history. |
USAGE_LIMITS_FETCH |
on | off keeps the panel and the hooks off the network; they show the reading already on disk. |
USAGE_LIMITS_REFRESH |
180 | Seconds a reading may age before the before-prompt hook takes a fresh one. The mid-turn pulse uses its own interval. |
USAGE_LIMITS_POLL |
30 / 120 | Seconds between the panel's readings, working / idle. Never under 15. |
USAGE_LIMITS_MOTION |
on | off stops the spinner, the shimmer and the rainbow. Claude Code's prefersReducedMotion setting does the same. |
USAGE_LIMITS_STATUSLINE |
on | off blanks the status line while still recording the feed the panel reads. |
USAGE_LIMITS_CLOCK |
from settings | 12h or 24h for reset times; otherwise follows Claude Code's timeFormat. |
USAGE_LIMITS_COLOUR |
detected | 256 or none to override colour detection. NO_COLOR and FORCE_COLOR are honoured. |
USAGE_LIMITS_ASCII |
off | 1 draws the bars and the spinner with plain characters. |
The other half of the question. After every reply, a Stop hook shows you one
line with what that reply cost and what the session has cost so far, tokens
first because that is what people ask:
[usage-limits] this reply: 6 turns, 210k tokens, $0.95. This session: 9 prompts,
48 turns, 3.1M tokens (2.9M cache read, 61k output), about $12.40, roughly 31
points of the 5-hour window. Context is now about 130k tokens.
It goes to you, not into the context, so it costs the model nothing. It reads
only the bytes of the transcript written since the previous reply, including
any subagent transcripts under the session's own folder, so it takes a few
milliseconds however long the session has run. When the session closes, a
SessionEnd hook prints the closing line:
[usage-limits] session closed after 1h 42m: 9 prompts, 48 turns, 3.1M tokens, about $12.40.
Claude is also asked to end finished work with the total in its own words, one plain line, and to skip it on partial progress. The before-prompt line carries the session's tokens, what the last reply cost, and how large the context has become, with one clause of advice once it passes 150k tokens, because the context is re-sent on every call and past a point it is the cost of the session.
The history is kept in usage-limits-sessions.json beside the other caches:
node skills/usage-limits/scripts/usage.js --sessions
node skills/usage-limits/scripts/usage.js --session last
Id When Project Prompts Turns Tokens Cost
4940f126 9m ago C--Users-OWNER 1 16 2.8M $11.36 open
380e664a 9m ago C--Users-OWNER 10 112+35 51.0M $93.11 open
--session last (or an id, or a unique prefix of one) shows one session in
full: the token split, the model mix, the subagent calls and the context size.
Installed as a plugin, /usage-limits:session reads the same thing back.
Turns are main-thread calls; +N is what subagents made on top. Set
USAGE_LIMITS_TALLY=off to turn all of this off.
If you installed the plain skill rather than the plugin, add the two hooks
beside the first one in settings.json: Stop running scripts/stop.js and
SessionEnd running scripts/sessionend.js.
node skills/usage-limits/scripts/usage.js --forecast 15
Forecast for 15 turns
Window Would cost Leaves Verdict
5-hour 7.4% to 8.4% 45% fits
weekly 0.8% to 0.9% 83% fits
Priced from 64 recent turns: $0.296 typical, $0.333 at the expensive end.
There is room for this. No need to work around the limit.
It prices turns at what turns have really cost on your account, and gives a range rather than one number, because a turn that reads three files costs many times one that answers from context. The upper end is the honest one for a long run, since turns get dearer as the context grows.
node skills/usage-limits/scripts/usage.js --recommend # against the headroom
node skills/usage-limits/scripts/usage.js --recommend 15 # against a 15 turn job
Recommendation for 15 turns
Posture tight - a 15 turn job fits, but only just (5-hour window, 12% left, resets in 1h 40m)
Effort xhigh -> medium; one notch covers the mechanical stretches; keep judgement calls at full effort
this session: /effort medium (only the user can run it)
new sessions: node scripts/lowpower.js on --effort medium
Model keep opus for the judgement; the saving is in where the mechanical bulk runs
dispatch self-contained mechanical work to a subagent on sonnet at low effort, and keep the judgement here
It weighs the binding window, the measured cost of a turn, and how much of the
output is actually reasoning, then names a posture - roomy, tight, critical, or
reset-first - and the exact commands. When there is room it says to keep
everything as it is, out loud, because turning effort down when the budget is
not tight buys nothing and costs quality. When reasoning is only a sliver of
the output it says so too, and leaves effort alone: the reasoning share is the
ceiling on what lowering effort can save. --json returns the decision as an
object.
The three levers it recommends across belong to different hands. The running
session's effort and model are the user's alone (/effort, /model, applied
immediately); new sessions belong to lowpower.js, which writes settings.json
for the next launch; and delegated work belongs to the agent itself, which can
dispatch a subagent on any model at any effort, mid-session, with no one asked.
No script or hook can change the model or effort of a session already running -
settings.json is read at launch and hook output has no model field - which is
why the recommendation separates "this session" from "new sessions" instead of
pretending one command covers both.
It reads which plan you are on and adjusts what it tells you, because the advice differs even though the arithmetic does not:
| Plan | Read from | What changes |
|---|---|---|
| Pro | claude_pro |
Smallest budget. The 5-hour window usually binds first. |
| Max 5x | claude_max plus default_claude_max_5x |
Room for Opus on most work. The weekly window is the one that bites. |
| Max 20x | claude_max plus default_claude_max_20x |
Rarely binds. No reason to slow down unless the weekly is already high. |
| Team, Enterprise | claude_team, claude_enterprise |
Seats are pooled and overage is an org setting. |
The window maths never needs to know the plan. It calibrates against what your own account reports, so it is right on any tier, including ones that did not exist when this was written. The plan only decides which line of advice you get at the bottom of the report.
It reads Codex's limits too, from the same repo and the same commands.
Codex writes its session rollouts to ~/.codex/sessions, one JSON object per
line, and every model request appends a record carrying both the account meter
and what that request cost in tokens. That is the same pair of things this tool
needs from Claude Code, so the window arithmetic, the turn estimates, the
forecast and the concurrent-session counting all work unchanged. Nothing is
uploaded and no credentials are read.
npx claude-usage-limits --host codex
npx claude-usage-limits --host codex --refresh
npx claude-usage-limits codex-hook on
The host is detected, so --host is only needed on a machine with both
installed. --refresh asks Codex itself for a live reading rather than the
newest one it happened to write; it starts a short-lived codex app-server and
takes about a second, and it is the Codex equivalent of /usage.
As a plugin, Codex installs it from this repo directly:
codex plugin marketplace add https://github.com/ridelink0/claude-code-usage-limits
codex plugin add usage-limits@usage-limits
The panel works under Codex too, GPT-6 Astra included:
npx claude-usage-limits panel --open --host codex
It reads Codex's own meter the way /status does, through a short-lived
codex app-server, and draws the same bars under the title Codex usage,
with the model named the way Codex names it. Codex has no status line and no
hooks, so there is no spinner for a working session and no Sessions list; the
numbers are the point.
Under Claude Code the budget line arrives on its own, because a plugin can ship hooks. Under Codex it does not, and not for want of trying:
- Codex has the whole hook engine. The binary carries
UserPromptSubmit,SessionStart,PreToolUseand the rest, andcodex features listreportshooksas stable and enabled. - A plugin cannot ship one:
plugin_hooksis reported asremoved. - And on
codex-cli 0.151.0-alpha.7.2nothing fires it. Tested with a hook whose only job was to write a file, from~/.codex/hooks.json, from a[hooks]table inconfig.toml, and from~/.codex/hooks/, in bothcodex execand the desktop app. The engine is present and inert.
So codex-hook on installs two things. A marked block in ~/.codex/AGENTS.md,
which Codex reads at the top of every session and which is what actually works
today; and the hooks themselves, ready for the build that runs them. status
reports both, off removes both, and neither touches anything else in those
files.
The practical difference is that under Codex the budget is read deliberately, once at the start of a piece of work, rather than being handed to you before every prompt.
Two smaller differences. There is no money column: Codex meters a share of an
allowance and never quotes a price, so the percentages stand alone. And
lowpower is Claude Code only, because it writes Claude's settings.json.
The Claude Code extension for VS Code shows the limits only when you ask with
/usage, and it does not render a custom status line. So there is an
extension of its own in vscode/: the same bars as a view that sits
directly under the Claude Code chat in the secondary side bar (it contributes
into the Claude Code extension's own view container, so there is no gap and
nothing to arrange), a status bar item with the percentages that turns yellow
and red at the same thresholds, the Sessions list, and the same animations in
CSS. It carries the plugin's scripts inside it, so it has no dependencies and
reads the same files and takes the same reading as the terminal panel.
cd vscode && npm run package
code --install-extension claude-usage-limits-<version>.vsix
The .vsix is attached to each GitHub release. It is not on the Marketplace
yet; that needs a publisher account, and the steps are in
vscode/README.md.
Every surface of Claude Code on a machine shares one config directory, so this reads all of them and does not care which one you are in:
| Surface | Works | Notes |
|---|---|---|
Terminal (claude) |
yes | |
| VS Code extension | yes | The VS Code extension above puts the bars under the chat and in the status bar. |
| JetBrains extension | yes | |
| Desktop app | yes | The budget line and the hooks. The panel, the status line and the VS Code extension are for the terminal and VS Code; the app shows the limits itself. |
Headless (claude -p) |
yes | Scripts run fine, but there are no slash commands, so lowpower.js is the only way to change effort. |
| Cloud and web sessions | partly | Those run on a remote machine with their own config directory. Percentages are per-account and stay correct; the pace is measured from whatever transcripts are local to wherever you run the script. |
Sessions from different surfaces land in the same ~/.claude/projects tree
and are counted together. On this machine the transcripts carry both cli and
claude-vscode entrypoints, and the report totals both.
Windows, macOS, and Linux all work. CLAUDE_CONFIG_DIR is honoured if you have
moved the config directory.
Half the problem is measurement. The other half is that a high effort setting keeps spending at the same rate whether or not there is room left.
node skills/usage-limits/scripts/lowpower.js status
node skills/usage-limits/scripts/lowpower.js on # effortLevel -> low
node skills/usage-limits/scripts/lowpower.js on --effort medium --model sonnet
node skills/usage-limits/scripts/lowpower.js off # puts back what was there
It edits effortLevel in settings.json through a temporary file, saves the
previous values alongside, and keeps a .usage-limits-backup copy of the original.
Keys it does not manage are left untouched. Running on twice does not
overwrite the saved originals.
The file change applies to new sessions. For a session already running,
/effort low does the same thing immediately.
--effort max is refused: settings.json does not accept max, so saving it
would store a value the next session silently ignores. max lives in
/effort and CLAUDE_CODE_EFFORT_LEVEL only.
That covers the setting. The larger saving is behavioural, and the skill file
spells it out: batch tool calls, read line ranges instead of whole files, skip
subagents when the context already exists, stop retrying a fix that is not
working. Effort level does not control any of that, which is why those rules
apply even at xhigh or max. The reasoning behind each one is in
tactics.md.
Node 18 or newer, and a Claude Code recent enough to write
cachedUsageUtilization into ~/.claude.json. If the report says it found no
snapshot, run /usage once inside Claude Code and it will be there.
Nothing is uploaded. The report and the status line read only files already on
the machine. The panel, and the hooks when the reading on disk is older than a
few minutes, take the same reading Claude Code takes for /usage: they read
the login token Claude Code keeps and send it to Anthropic's usage endpoint,
nowhere else. The token is never written to disk by this plugin, never
printed, and never refreshed or rotated. USAGE_LIMITS_FETCH=off keeps all of
it offline, on the reading Claude Code itself last cached.
Good enough to plan with, not a bill. The honest caveats:
- The meter reports whole percent, so a reading of 2 percent is really somewhere between 1.5 and 2.5. Low readings project badly, and the report says so when it is in that range.
- Transcripts are local. Usage from another machine or from claude.ai counts against the same limit but leaves no local record, which makes the estimate read low.
- The dollar figures are an internal unit used to convert your token mix into a percentage of the limit. On a subscription plan you are not billed them.
- Turns left assumes the next turns look like the last hour's. A debugging spiral breaks that assumption immediately.
- A model released after this table was written is priced at its family's average rate, and the report marks those rows with an asterisk rather than passing the guess off as a published price.
- Time of day is not modelled. Anthropic used to shrink the five-hour limit during peak hours, but removed that on 6 May 2026 for Pro and Max while doubling the limits. If demand-based limits ever return, the numbers here follow automatically, because they are calibrated from what your traffic did to the meter rather than from an assumption about the clock.
- Subagent transcripts, written under the session's own folder, are read too. Their calls count in the money and the tokens and are reported apart from the turns, because a turn is one main-thread call.
- The account's own list of limits is read as well as the per-window buckets,
so a per-model weekly such as
weekly (Fable)shows up as a window of its own, priced from that model's calls alone. - A per-model weekly only counts against you while you are running that model.
One at 88 per cent is not your wall if you are working on Opus: nothing you
do moves it. Those windows are still listed, marked
not in use, but they are never picked as the binding window, never raised as a warning, never a reason a forecast says the job does not fit, and never what putsLOWon the status line. Start using that model and they come straight back. Nothing is suppressed unless both sides are recognised: an unknown model in the setting, or a weekly scoped to a model this table has never heard of, is treated as live, because hiding a limit that can stop the work is worse than showing one that cannot. - The report also says what the room left buys in turns of each model, priced
from that model's own measured cost per turn, against the window its spend
lands in. Rows sharing a window are alternatives rather than additions. A
model that has only ever run as a subagent gets no projected turn count at
all - its errands are not turns - though what delegating to it has cost is
still reported. What each model cost is remembered in
usage-limits-models.json, one entry per family, so a session that opens on a model it has not run this week still knows its price. - The turn cost behind "turns of headroom" is a median over at least five turns, so one compaction cannot define your pace.
- What a point of a window costs is learned once from the best sample seen and remembered, rather than re-derived each time from whatever slice is to hand. A thin baseline prices a point badly and every correction built on it inherits the error, which is how a window truly at 70 percent once came out at 82.
- The cache only refreshes when Claude Code talks to the API, so after a gap it
can be hours old and its 5-hour window long since rolled over. Dropping that
window would hide the limit that actually stops short work, so it gets rebuilt
from your transcripts instead: whatever was spent inside the window the stale
reading describes equalled its percentage, and that price per point still
values the window running now. Rebuilt figures are written
~41%in the report and "about 41%" in the before-prompt line, and they say how old the snapshot is so you can run/usageand replace the estimate with a reading. - A rebuilt figure only counts what this machine did. If you also worked on another device it reads low, which is the dangerous direction, so treat it as a floor until you refresh.
- If a rebuild comes out above a full window, it is refused rather than capped.
Local transcripts only see this machine, so a window mostly spent elsewhere
makes a point look far too cheap and any live spend divides to hundreds of
percent. Capping that at 100 would tell someone sitting at half their budget
that it was gone. The window is reported as unknown instead, with a nudge to
run
/usage.
how-it-works.md has the field names, the formulas, and the rest of it.
.claude-plugin/plugin.json plugin manifest, Claude Code
.claude-plugin/marketplace.json lets the repo serve itself
.codex-plugin/plugin.json plugin manifest, Codex
agents/openai.yaml how Codex lists the plugin
skills/usage-limits/SKILL.md what the agent reads
skills/usage-limits/agents/ how Codex lists the skill
skills/usage-limits/scripts/ usage.js, brief.js, pulse.js, stop.js,
sessionend.js, tally.js, codex.js, host.js,
lowpower.js, install-codex-hook.js,
recommend.js, panel.js, feed.js,
statusline.js, live.js, view.js, bars.js,
activity.js
skills/usage-limits/references/ the longer notes
hooks/hooks.json runs brief.js before each prompt, pulse.js
during long turns, stop.js after each reply
and sessionend.js when the session closes
commands/check.md the /usage-limits:check command
commands/session.md the /usage-limits:session command
commands/panel.md the /usage-limits:panel command
commands/statusline.md the /usage-limits:statusline command
bin/cli.js the npx entry point
tools/sync-version.js keeps the manifest version in step
vscode/ the VS Code extension; build.js copies the
scripts into vscode/lib and makes the vsix
test/ node --test, no dependencies
node --test
477 tests over the pricing, the window arithmetic, plan and credit detection, the status line, the before-prompt line, the mid-turn pulse, the after-reply tally and the session history, job forecasting, per-project attribution, the Codex reader and its installer, the CLI, packaging, and the settings save/restore.
It works and I use it daily.
What I am not doing is fielding feature requests or support questions. If you want it to behave differently, fork it and change it, which is what the MIT licence is there for. Do not wait on me to add something for you.
MIT. See LICENSE.