claude-usage
BenjaminHolderbein/claude-usage
Claude Code skill to check your Claude usage limits (5-hour + 7-day windows) from the terminal.
Instalação
npx convez-ai BenjaminHolderbein/claude-usage1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
claude-usage
A Claude Code skill that reports how much of your Claude (Anthropic) usage limit you've consumed — the rolling 5-hour session window and the 7-day limits — without leaving your terminal.
It reads the same OAuth token Claude Code already stores and queries the same
endpoint the built-in /usage command uses, then prints a clean summary:
Claude usage limits
5-hour session 8% resets Thu Jun 11, 4:40 PM PDT
7-day (all models) 15% resets Mon Jun 15, 12:00 PM PDT
7-day Opus not tracked
7-day Sonnet 0% resets Mon Jun 15, 12:00 PM PDT
extra usage disabled (hard stop at limit)
Why
Claude Code ships a /usage slash command, but it only works inside an
interactive session. This packages the same data as:
- a skill, so you can just ask Claude "where am I on my usage?" and it answers, and
- a plain script you can run from any shell, drop in a status bar, or wire into automation.
Requirements
- macOS — the script reads the OAuth token from the login Keychain
(service
Claude Code-credentials). On Linux the token lives in~/.claude/.credentials.jsoninstead; see Linux below. - Claude Code, signed in at least once.
python3andcurl(both present by default on macOS).
Install
Clone anywhere, then symlink it into your Claude Code skills directory so the skill is discoverable:
git clone https://github.com/BenjaminHolderbein/claude-usage.git
ln -s "$(pwd)/claude-usage" ~/.claude/skills/claude-usage
That's it — Claude Code picks up the skill on next launch.
Usage
As a skill, just ask in any Claude Code session:
where am I on my usage limit?
Or run the script directly:
bash ~/.claude/skills/claude-usage/usage.sh # human-readable summary
bash ~/.claude/skills/claude-usage/usage.sh --json # raw JSON
Use cases
-
Quick check — "where am I on my usage?" / "am I close to my limit?"
-
Budget a session against your limit. Tell Claude how much of your usage to spend and let it self-govern:
- "Use 10% of my limit thinking this through."
- "Spend up to a quarter of my usage on this refactor."
- "Use my whole limit — go as deep as you can."
The skill reads your current 5-hour utilization to set a ceiling (
current + N%), works in chunks, re-polls between them, and keeps going until the meter actually reaches the budget (it also watches the 7-day limit, since that's the harder wall). The reported percentage is the same number Anthropic's official usage page shows — verified by reading both side by side while burning tokens — so Claude steers by a real meter, not a guess. Its only limit is 1-point resolution (the same as the official UI), which is plenty for a "spend N%" budget.
How it works
- Pulls your OAuth access token from the macOS Keychain.
GET https://api.anthropic.com/api/oauth/usagewith that token and theanthropic-beta: oauth-2025-04-20header.- Formats the
utilization/resets_atfields for each limit window into a table, converting reset timestamps to your local time zone.
It is strictly read-only — it never writes or mutates anything.
Response fields
Each window is a bucket with utilization (0–100 percent) and resets_at
(ISO 8601). Notable keys:
| Field | Meaning |
|---|---|
five_hour | Rolling 5-hour session window. |
seven_day | 7-day rolling limit across all models. |
seven_day_opus / seven_day_sonnet | Per-model 7-day buckets. Often null (not separately tracked). |
extra_usage | Overage billing. is_enabled: false means usage hard-stops at the limit instead of spilling into paid credits. |
Linux
The script reads the Keychain, which is macOS-only. On Linux the token is in
~/.claude/.credentials.json; swap the token line for:
TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.claude/.credentials.json')))['claudeAiOauth']['accessToken'])")
Caveats
- The usage endpoint is undocumented and used internally by Claude Code; it could change without notice.
- If the API returns
401, your access token has expired — Claude Code refreshes it the next time you launch it.
License
MIT © 2026 Benjamin Holderbein