| name | usage |
| description | Show Claude subscription usage — current 5-hour session % and 7-day weekly % used, plus reset times. Mirrors the "Usage" view in the Claude.ai mobile app. Use when the user asks about their Claude usage, quota, limits, or how much of their session they've burned. |
| requires | {"bins":"curl, python3"} |
| setup | No setup. Reads the OAuth token Claude Code already stores at ~/.claude/.credentials.json.
|
Claude Usage
Reports the same numbers Claude.ai shows in its Usage screen: current session and weekly limit, with utilization % and reset times.
How it works
Anthropic returns rate-limit headers on every API response. Claude Code reads them; we just read them too. The relevant headers:
anthropic-ratelimit-unified-5h-utilization — fraction of the 5-hour session used (0.0–1.0)anthropic-ratelimit-unified-5h-reset — Unix epoch seconds when the session resetsanthropic-ratelimit-unified-7d-utilization — fraction of the 7-day weekly limit usedanthropic-ratelimit-unified-7d-reset — Unix epoch seconds when the weekly resets
To trigger a response with those headers we make the cheapest possible call: claude-haiku-4-5, max_tokens: 1, prompt "x". Cost is fractions of a cent and counts against the same limits we're measuring (so the report is honestly post-call).
Run it
bash skills/usage/run.sh
Output is plain text with two bars (session, weekly), percentages, and resets in Xh Ym.
Auth
Reads the OAuth access token from ~/.claude/.credentials.json (the file Claude Code itself writes when you log in with your Claude subscription). API key auth would also work but the headers are tied to the auth used; we want the subscription limits, so we use the OAuth token.
When to use
The user mentions:
- "how much usage have I used", "what's my session at", "weekly limit", "quota"
- references to the Claude.ai app's Usage screen
- a Telegram
/usage slash command
When NOT to use
- The user is asking about API spend in dollars — that's a different question; this skill reports subscription utilization, not billing.
- The user is on an API-key-only setup (no Claude subscription); the headers will reflect API-key tier limits which may differ from what they see in the Claude.ai app.
