claude-usage

Your real Claude plan limits — the same percentages /usage reports — in the macOS menubar and in the Claude Code status line.

✳ 82% ↺46m · W77% · F41%

That reads: 82% of the current 5-hour session window used, resetting in 46 minutes; 77% of the weekly all-models allowance; 41% of the weekly Fable-5-scoped allowance. Clicking through adds reset times, today's token count, and the current block's burn rate.

Two independent pieces, install either or both:

File	What it does
claude-usage.1m.js	SwiftBar/xbar menubar plugin. Refreshes every minute (the .1m. in the filename sets the cadence).
statusline-usage.js	Claude Code status line command. Appends the plan percentages to ccusage's own status line.

Why this exists

ccusage is excellent, but it reports the estimated API list-price value of your token usage, computed from local logs. On a flat-rate plan that number is not a bill and not a limit — it can read $170 on a day you are nowhere near being throttled. The thing you actually want to know is how close you are to the rate limits, and that only comes from Anthropic's usage endpoint.

This shows both, clearly separated: plan percentages up top, estimated API value underneath.

Install

git clone https://github.com/kenjichristopherv-del/claude-usage.git
cd claude-usage
./install.sh

install.sh symlinks rather than copies, so git pull updates both scripts in place. It prints the one line you need to add to ~/.claude/settings.json for the status line.

Requirements

• macOS — plan data comes from the login token in the Keychain, and the menubar half needs SwiftBar (brew install --cask swiftbar) or xbar.
• Node 18+ — for built-in fetch. The scripts find node at /opt/homebrew/bin, /usr/local/bin, or on PATH; set CLAUDE_USAGE_NODE to point at a specific binary if yours lives elsewhere (nvm, volta, asdf).
• ccusage — optional, and only for the cost figures. bun add -g ccusage, or npm. Found automatically in the usual install locations; override with CCUSAGE_BIN. Without it the plan percentages still work.

How the data flows

Plan percentages — the OAuth token is read from the macOS Keychain item Claude Code-credentials (the one Claude Code already created when you logged in; nothing new is stored and no token ever leaves your machine), then:

GET https://api.anthropic.com/api/oauth/usage
    Authorization: Bearer <token>
    anthropic-beta: oauth-2025-04-20

limits[] in the response carries session (the 5-hour window), weekly_all, and weekly_scoped entries — each with a percent and a resets_at. Any scoped limit beyond Fable is listed too, so this keeps working if the plan structure changes.

Cost figures come from ccusage reading ~/.claude/projects/**/*.jsonl. Estimated API list-price value of tokens spent — useful as a relative signal, not a charge.

Caching, and why it matters

Both scripts share one cache at ~/.claude/.usage-cache.json with a 60-second TTL, so running the menubar plugin and the status line together does not double the request rate.

The status line renders on every turn, which makes a naive implementation a good way to rate-limit yourself. Two things prevent that:

• Refreshes happen in a detached child process (--refresh), so drawing the status line never blocks on the network.
• On failure the script writes a 5-minute backoff into the cache and keeps serving stale data. Without this, a 429 leaves the cache stale, which makes every subsequent render think a refresh is due, which spawns another request — a stampede that keeps you rate-limited. The refresh slot is also claimed before spawning, so concurrent renders don't each fire one.

When data is being served stale, the menubar dropdown says so with the time it was last fetched, rather than silently showing old numbers.

Troubleshooting

Menubar shows "Plan usage unavailable (token/keychain?)" — the Keychain read failed. Confirm the item exists: security find-generic-password -s "Claude Code-credentials" -w. If it prompts for permission, allow it. If it is missing, log in to Claude Code again.

Menubar is blank or shows a node error — SwiftBar runs plugins with a minimal PATH. Set CLAUDE_USAGE_NODE=/path/to/node in SwiftBar's environment, or edit the first two lines of the plugin.

Cost shows "ccusage not found" — install it, or ignore it; the plan percentages are independent.

License

Apache 2.0 — see LICENSE.

Not affiliated with Anthropic. The usage endpoint it reads is the one Claude Code's own /usage command uses; it is undocumented and could change.