| name | usage |
| description | Report real Claude Code session-quota state — percent of the 5-hour and 7-day windows used, reset times, and status (ok/warning/rejected). Same numbers Claude Code's own statusline reports. Use when the user asks about usage, quota, rate limits, or when auto-engineer's quota gate calls `/usage`. |
usage
The authoritative source for session-quota state is the set of anthropic-ratelimit-unified-* response headers Anthropic attaches to every /v1/messages call. Claude Code reads them into memory and feeds them to its statusline — they are the real numbers, not an estimate.
Since that state lives only in the running Claude Code process, this skill fetches it by making a minimal 1-token probe call and parsing the headers. Result is cached for 60s at ~/.claude/cache/usage-probe.json so repeat invocations are free.
Primary command
bash .claude/skills/usage/probe.sh
(Add --force to bypass the 60s cache.)
Output is a single-line JSON like:
{"http":200,"fetched_at":1776054016,
"5h":{"utilization":0.38,"resets_at":1776056400,"status":"allowed"},
"7d":{"utilization":0.33,"resets_at":1776567600,"status":"allowed"},
"overage":{"utilization":0.0,"resets_at":1777593600,"status":"allowed"}}
Fields: utilization is 0..1+ (can exceed 1 when the window is over-consumed), resets_at is Unix epoch seconds, status is allowed / allowed_warning / rejected.
Output format
Always emit these two machine-readable lines first (auto-engineer step 9 parses them):
remaining_pct: <max(0, 100 - 5h.utilization*100), rounded to 1 decimal>
reset_ts: <ISO-8601 of 5h.resets_at>
Then a short human summary: 5h %, 7d %, overage %, each window's status, time-until-reset, and a note if status=rejected (Claude Code is currently blocked on that limit until reset).
Fallback
If the probe returns an error (no credentials, non-200, missing headers), fall back to ccusage:
npx -y ccusage blocks --active --token-limit max --json
Label fallback output clearly as estimated — ccusage benchmarks against the user's all-time largest block, not the plan's real cap, so its percentage is routinely off vs. the probe. Use projection.remainingMinutes and endTime from .blocks[0].
Caveats
- The probe costs one tiny Haiku call (~22 in / 1 out, well under $0.001). The 60s cache keeps this negligible.
overage appears only on plans where extra-usage is enabled; absent otherwise.- If the user is fully rate-limited (
5h.status == "rejected"), the probe itself still succeeds — Anthropic returns headers on 200s and rejects only subsequent inference calls. If it ever fails with 429, report remaining_pct: 0 and surface the cached reset_ts from a prior probe if one exists.
