Claude usage check

Report the user's current Claude usage against their limits by running the bundled script. It reads the Claude Code OAuth token from the macOS Keychain and queries https://api.anthropic.com/api/oauth/usage (the endpoint behind the built-in /usage command).

How to run

bash ~/.claude/skills/claude-usage/usage.sh          # human-readable summary
bash ~/.claude/skills/claude-usage/usage.sh --json   # raw JSON

Run it, then relay the result to the user. Lead with the headline numbers (5-hour session % and 7-day %), note the reset times, and flag anything notable (e.g. close to a limit, or extra-usage billing disabled meaning a hard stop).

Budgeted sessions

When the user frames a task as a usage budget — "use 10% of my limit on this", "spend up to a quarter of my usage", "use my whole limit thinking this through" — treat the 5-hour session window (five_hour) as the meter, since that's the one a single working session actually moves. Steps:

1. Set the ceiling. Run the script to read the current five_hour utilization. A budget of N% means N more percentage points, so the ceiling is current + N (cap at 100). "Use my whole limit" → ceiling 100%. Tell the user the baseline and the target before you start (e.g. "5-hour is at 8% now; I'll work until ~18%").
2. Work in chunks, then poll. Do a meaningful slice of the task, then re-run the script to see where utilization landed. Poll between chunks rather than after every action — roughly every few tool-heavy turns — because the meter moves in 1-point steps and a single session moves it slowly (it takes hundreds of thousands of tokens to move a few points), so checking after every turn just shows the same number.
3. Stop at the ceiling. When five_hour reaches the target, wrap up: summarize what got done and what remains. Don't blow past the budget — and don't stop short of it either. Keep working and re-polling until the meter actually reaches the ceiling.
4. Watch the 7-day too. If seven_day would cap out first, stop there and say so — the weekly limit is the real wall.

If the user gives no budget, don't impose one.

The meter is accurate — do not dismiss it

This has been verified empirically (refreshing the official usage page and the script side by side while burning tokens): the script reports the exact same number as Anthropic's official usage page, because it reads the same backend endpoint. It is not a lagging, unreliable, or merely-approximate indicator.

Do not use "the tool is a lagging indicator" or "it's unreliable" as a reason to stop a budgeted session early or to guess at the percentage instead of reading it. That reasoning is wrong, and it is the documented failure mode this skill exists to prevent. If you've been asked to spend a budget, the only way to honor it is to actually run the script and keep going until the number reaches the ceiling — not to stop when it "feels" like enough.

What is true about the meter (none of which makes it unreliable):

• Resolution is 1 percentage point. The endpoint returns integer percents, so sub-1% changes aren't visible. This is the same resolution the official UI shows — it's a granularity limit, not inaccuracy.
• It settles within a few seconds after a burst of usage and then reads steady at the correct value. Re-running the script a few seconds apart and seeing the same number means it has settled, not that it's stuck — trust it.

What the endpoint returns

Each window is a bucket with utilization (percent, 0–100) and resets_at (ISO timestamp). Key fields:

• five_hour — the rolling 5-hour session window.
• seven_day — the 7-day rolling limit across all models.
• seven_day_opus / seven_day_sonnet — per-model 7-day buckets. Often null (not separately tracked) — report those as "not tracked", not 0%.
• extra_usage — overage billing. is_enabled: false means usage hard-stops at the limit instead of spilling into paid credits.

Notes

• The token lives in Keychain under service Claude Code-credentials. If the script can't read it, the user may need to re-authenticate Claude Code.
• This is read-only; it never mutates anything.
• If the API returns a 401, the access token has expired — Claude Code refreshes it on next launch.