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. They did: five consecutive runs died between the evening of August 10 and the morning of August 11, and repricing the same fleet's transcripts against list API rates put a figure on what that ceiling is buying.

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.

Update, 2026-08-13. The same question came up for a different vendor, with the opposite answer. When Cloudflare shipped a cost API aimed at programs, I assumed my rig could poll it the way it now polls /usage, and the deploy token got a 403 whose message names authentication rather than the missing permission. The lesson from this post was to run the one-line experiment instead of trusting my own summary; running it that time reversed my claim, and this time it confirmed the wall.

Update (2026-08-15): /usage is not the only readable surface open to -p. /context and /autocompact both carry supportsNonInteractive in the binary and return at num_turns: 0 for zero cost, which is how I read the auto-compact window and the 33K buffer behind the compaction threshold without spending a token. Running the one-line experiment kept paying.

Update, 2026-08-15: the pattern has a limit

This post argued that I had assumed a slash command was interactive-only without running the one-line test. Working the same test across other commands drew the boundary. /usage and /context both answer headless; /hooks does not, returning /hooks isn't available in this environment with num_turns 0 in 16 milliseconds. That matters because /hooks is the documented way to verify hook configuration, which leaves an unattended fleet with no supported way to check. I wrote up what does work in a post on telling whether a Claude Code hook actually ran.

Update, 2026-08-16: /usage is not the only cost command that survives -p, and the sibling most people reach for first returns nothing useful on a subscription. claude -p "/cost" is an alias for /usage that reports no dollar figure at all, a merge recorded in the 2.1.118 changelog. Probing the rest of that ladder put a number on the documentation gap this post noticed: of 106 rows in the commands table, 8 carry a non-interactive annotation, and it does not predict which of the other 98 actually run headless.

Update, 2026-08-27: the meters this command prints include a dedicated current-week line for Fable 5, separate from the all-models weekly figure. Which wall goes up when that one fills — and why its failure message varies from machine to machine — is measured in the Fable 5 limit post.

Update, 2026-09-02. Two changes since this was measured. The claude -p "/usage" output has grown an attribution panel that names which behaviors spend the meter (long-context, subagent-heavy, parallel sessions), and the weekly limit itself drops 17% against today’s boosted level on September 14. Both are documented in the weekly limit increase post.

Update, 2026-09-03

Two additions since this was written. The rate_limits.five_hour.resets_at field documented for custom status lines is not delivered under claude -p: a status line command configured through --settings never executed in a headless test, so /usage remains the only headless reading. And the 8:59pm above is the /usage renderer's one-minute quirk; the error messages themselves land on a 10-minute grid in 128 of 128 observations, measured in the 5 hour limit reset post.

Update (2026-09-06): I have since done a census of the third-party monitors that read this same endpoint or the transcripts: 32 Claude Code usage monitors grouped by what they read, with ccusage run against my own files. Only the OAuth and status line tools can see the percentage discussed above; the JSONL tools price tokens and cannot.

Update, 2026-09-13: the headless status line test above now has numbers behind it. I re-ran the probe on 2.1.268 (zero invocations in a full claude -p session) and classified 1,039 statusline issues in why the Claude Code statusline is not working; print mode is reason one of six, and rate_limits being absent for API-key users is reason six.

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.