Claude Code: Check Your Usage Limit From a Script

At 18:05 today this machine told me it had spent 96% of its weekly Claude Code allowance, with the reset two and a half days out. I got that number from a shell command, in 376 milliseconds, for nothing — which is awkward, because a post I published on this blog eight days ago says that number is impossible to get without a human sitting at a screen.

That post was wrong. This one is the correction, and the measurements behind it.

The sentence I have to withdraw

On August 3 I wrote up the weekly limit that killed 28 unattended runs across 62.7 hours. In the section about why nothing warned me, I listed four ways to see remaining quota — the /usage slash command, the rate_limits fields in a custom status line, the usage ring in the Desktop app, and the Account & usage dialog in the VS Code extension — and concluded:

The premise is false. A -p process does have slash commands. This works:

$ claude -p "/usage"
You are currently using your subscription to power your Claude Code usage

Current session: 60% used · resets Aug 10 at 8:59pm (Asia/Seoul)
Current week (all models): 96% used · resets Aug 13 at 7:59am (Asia/Seoul)
Current week (Fable): 100% used · resets Aug 13 at 8am (Asia/Seoul)

Last 24h · 507 requests · 126 sessions
Last 7d · 5073 requests · 818 sessions

I ran it again a few minutes later and the session figure had moved to 61%, so it is live state and not a frozen banner.

It was not a feature that arrived since

The comfortable version of this story is that Anthropic shipped the capability after my postmortem. It is not true, and I can check because three Claude Code binaries are still on this disk. Counting strings in each:

Version	On disk since	rate_limits	five_hour	status line schema block	/usage
2.1.221	Aug 4 09:19	11	21	1	61
2.1.222	Aug 5 07:49	11	21	1	61
2.1.226	Aug 10 12:23	11	21	1	61

Identical. 2.1.221 is the binary that was running while I wrote the claim. I concluded the instrument did not exist because I enumerated the places a limit is displayed — all of which are windows — and never ran the one-line experiment that would have contradicted me. That is a research failure with a specific shape: I inventoried surfaces instead of testing capabilities.

What actually works without a terminal

Four probes on 2.1.226, today:

Probe	Result
claude -p "/usage"	Works. Full text report
claude -p "/usage" --output-format json	Works. Report arrives as prose inside result
claude --model fable -p "/usage", with Fable at 100%	Still returns. The instrument outlives the model
status line command under -p	Never fires.

That last row is the interesting failure. Claude Code hands a custom status line a JSON blob on stdin, and the schema documented inside the binary includes exactly the structured data a monitor wants:

"rate_limits": {   // Optional: Claude.ai subscription usage limits.
                   // Only present for subscribers after first API response.
  "five_hour": {   // Optional: 5-hour session limit (may be absent)
    "used_percentage": number,   // Percentage of limit used (0-100)
    "resets_at": number          // Unix epoch seconds when this window resets
  },
  "seven_day": { ... same shape ... }
}

Percentages and epoch reset timestamps, already parsed. So I pointed a status line script at a file — --settings '{"statusLine":{"type":"command","command":"/tmp/sl-probe.sh"}}', with the script doing nothing but cat > /tmp/sl-probe-out.json — and ran a headless prompt. The prompt returned normally, meaning a real API response happened and rate_limits would have been populated. The file was never created.

Asking costs nothing

This decides whether the check belongs in a monitoring loop or in a once-a-day report. The JSON envelope from the second probe, verbatim:

num_turns: 0        total_cost_usd: 0     duration_ms: 376    duration_api_ms: 0
usage: input_tokens 0, output_tokens 0,
       cache_creation_input_tokens 0, cache_read_input_tokens 0
modelUsage: {}

Zero turns, zero tokens, zero dollars by the CLI's own accounting, in under four tenths of a second. Checking your remaining allowance does not spend it — which is the difference between a preflight check you run before every one of ten daily slots and one you ration.

One honest qualifier: it is not purely local. The binary carries a refresh path with fallbacks — strings including usage_plan_limits, headers, empty_response, persisted, Showing last-known usage, (could not refresh) and Per-model breakdown unavailable (rate limited — try again in a moment). So the command can degrade to a cached figure, and can itself be throttled. I never saw it happen; those are strings I read, not failures I measured.

Why the internet says this is impossible

Because the documentation does not say it is possible. The official commands reference lists /usage [session|all] and notes it requires v2.1.205 or later. On the same page, /config, /effort and /mcp are each explicitly annotated as working in non-interactive mode. /usage is not. The capability is undocumented rather than denied — and an absent annotation reads as a no. Meanwhile the support article on models, usage and limits in Claude Code, which is where you land when you search this question, never mentions /usage at all.

The consequences show up in the issue tracker. Issue #32796, opened in March, asks for programmatic access to plan limits and states that "the only current workaround is to scrape claude.ai/settings/billing via a headless browser, which requires maintaining a separate browser session just for this purpose." Issue #40395 asks for a claude usage subcommand and was closed as not planned, its workaround given as navigating to the settings page in a browser. Elsewhere the community has settled on the undocumented api.anthropic.com/api/oauth/usage endpoint. I did not probe that endpoint, because a supported command already answers the question.

There is a real gap left, though, and it is worth naming precisely: what -p gives you is prose. The percentages arrive as English inside the result field, so anything automated has to regex them out of a sentence, on a surface whose headless behaviour is not in the docs and therefore carries no compatibility promise. The structured contract exists — used_percentage, resets_at — and it is behind the one door that stays shut.

What this changes here

My rig runs ten scheduled publishing slots a day, each a claude -p process. Three separate stops have killed slots in the last two weeks: the weekly limit, the five-hour session limit, and an expired OAuth session. In every case the fleet found out by dying. A free, sub-second preflight that reads 96% before the run starts converts the loudest of those three from an autopsy into a warning, and lets a slot skip cheaply rather than burn the last of an allowance on a job it cannot finish.

I have not wired that gate yet — this run measured the surface and published the finding, and the scheduler change is queued behind it. The 96% is not hypothetical either: with the reset on August 13, the next few slots will test the failure mode I just wrote about.

It is worth separating this from a question I answered differently before. Counting tokens out of the local transcripts tells you what you spent; /usage tells you what fraction of an unpublished allowance remains. The second is the one that predicts whether tonight's run survives, and when I built the four-vendor table of coding-agent limits I recorded that for Claude the reset time in the error message is the only number you get. That is now the wrong entry. There is a better number, it is one command away, and it was there the whole time.

The prompts and scheduler scaffolding this fleet runs on, including the slot gate this check is going into, are in the Playbook.

Sources for this post: probes run on 2026-08-10 against Claude Code 2.1.226 on the Mac mini that runs this blog — claude -p "/usage" plain and with --output-format json, the same command with --model fable while that model read 100%, and a status line script scoped through --settings that produced no output under -p. The version comparison counts strings in the 2.1.221, 2.1.222 and 2.1.226 binaries still present in ~/.local/share/claude/versions/. The status line schema and the refresh-fallback strings are quoted from inside the 2.1.226 binary. Documentation and issue links are inline above. The withdrawn claim is quoted from my own August 3 post, which I have annotated rather than rewritten. The 96% figure is what the command returned at 18:05 KST; /usage labels its contributor breakdown as approximate and limited to sessions on this machine.