claude-usage
Skill0 starsChanged 4 months agoMITView on GitHub
Check how much of the Claude Code subscription is left, when limits reset, estimated per-model token headroom, and Anthropic API spend — via the local claude-usage tool (claude_usage.py). Use this skill whenever the user asks "how much usage / quota / credits do I have left", "am I close to my limit", "when does my limit reset", "how many tokens can I still use", "what's my Claude Code usage", "how much have I spent on the API", or wants this reported on a schedule / as a cron job. Trigger even when phrased loosely ("am I about to run out?", "check my limits") — prefer running this tool over guessing, since the numbers are live.
- Reads credentials
6 other projects use a version of this.
Adopted by
Most recently taken up by
- stv-io/claude-skillstheir own version, first seen Nov 15, 2026
- jakeonrails/claude-usagetheir own version, first seen Aug 12, 2026
- BenjaminHolderbein/claude-usagetheir own version, first seen Jun 13, 2026
- tdimino/claude-code-minoantheir own version, first seen Apr 16, 2026
- lucasmocellin/claude-skillstheir own version, first seen Apr 12, 2026
- thaitype/skillstheir own version, first seen Mar 15, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- tdimino/claude-code-minoan★ 41same name
- thaitype/skills★ 13same name
- jakeonrails/claude-usage★ 1same name
- BenjaminHolderbein/claude-usage★ 0same name
- lucasmocellin/claude-skills★ 0same name
- stv-io/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 49
Read these distinctions back to the user — they're easy to conflate:
- Distinctive: line 85
Never print the key, never commit it, and never paste it into chat output.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
claude-usage
A small, dependency-free Python tool that reports Claude Code subscription usage limits, reset times, per-model token headroom, and Anthropic API spend. Prefer running it over answering from memory — the figures are live and change constantly.
Where it lives
claude_usage.py at the repo root. It's executable and needs only Python 3.9+
(standard library). Run it with an absolute path if the working directory is
elsewhere.
How to run it
Pick the flag that matches what the user asked. Default (no flags) answers the common "how much is left / when does it reset" question.
| User wants… | Command |
| Current usage % + reset times | ./claude_usage.py |
| Machine-readable output (for scripts/cron) | ./claude_usage.py --json |
| The complete raw API payload | ./claude_usage.py --raw |
| Per-model token headroom estimate | ./claude_usage.py --estimate |
| Anthropic API spend (needs Admin key) | ./claude_usage.py --api-credits |
| Everything together | ./claude_usage.py --estimate --api-credits |
| Alert when a window crosses a threshold | ./claude_usage.py --threshold 85 |
--days N sets the API-spend window for --api-credits (default 30).
--threshold N makes the tool exit 1 when any window is ≥ N% used — use it
for cron/launchd alerting. Exit codes: 0 ok, 1 threshold breached, 2 error.
What each number means
Read these distinctions back to the user — they're easy to conflate:
- Subscription windows (
five_hour,seven_day, per-model weekly) report % used / % left and an ISO reset time. The 5-hour window is usually the binding one. This is the answer to "how much usage do I have left." - Extra-usage credits = pay-as-you-go overflow on the subscription. If
extra_usageis absent/disabled, the user has none — once subscription limits are hit, work stops. They enable or buy these with/usage-creditsinside Claude Code (formerly/extra-usage). - API console credits (
console.anthropic.comprepaid balance) are a separate billing account.--api-creditsshows consumed API spend via the Admin API — it is not a remaining-balance figure. No public endpoint exposes the remaining prepaid balance; that's only in console Billing.
The token estimate is approximate — say so
--estimate recovers each window's budget from local session logs: it measures
what was actually spent in the window, treats that as utilization% of the
budget, backs out the total, and converts the remainder to tokens per model at
API list prices (the subscription discount cancels, so the result is
discount-independent). When utilization is low the back-out amplifies noise, so
present these as order-of-magnitude, and note output tokens are the scarce side
(cached input is far cheaper, so real headroom is higher).
The model list is read live from /v1/models; prices come from
pricing.json (edit that file when prices change — don't hardcode
model names in code). The output's models_source says live_api or
pricing_config (the fallback when the API is unreachable).
Credentials
- Subscription data uses the local Claude Code OAuth token (macOS Keychain
or
~/.claude/.credentials.json) — no setup. A 401 means the token expired; tell the user to runclaudeonce to refresh. --api-creditsneeds an Anthropic Admin key (sk-ant-admin…), read fromANTHROPIC_ADMIN_KEYor the gitignored.secretsfile. Never print the key, never commit it, and never paste it into chat output.
Scheduling
For a recurring check, wire the --threshold form into cron or launchd and act
on the exit code / --json output. Example cron line:
*/30 * * * * /path/to/quotabar/claude_usage.py --threshold 85 >> ~/claude-usage.log 2>&1See README.md for full details.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

