usage-cache
One shared, cached read of your Claude plan usage, so every statusline stops polling on its own.
The problem
A Claude Code statusline in every session, a dev shell, a menu-bar meter: each one polls for your plan usage on its own. The usage endpoint rate-limits per token, so together they use up the budget, get HTTP 429 back and show stale numbers. usage-cache makes them share one cached read. However many clients you run, that's one request per interval.
Get it
npm i -g @excellent-so/usage-cache{ "statusLine": { "type": "command", "command": "usage-cache --statusline" } }usage-cache # "34%", the 5-hour session figure
usage-cache --statusline # "34% (5h) · wk 61%"
usage-cache --json # the full result object
usage-cache --ttl 30 # cache freshness window, in seconds (default 60)How to use it
- Install it with
npm i -g @excellent-so/usage-cache. It needs Node 18 or later and a Claude Code login on the same machine. - Point your statusline at
usage-cache --statuslinein~/.claude/settings.json. - Point every other meter at
usage-cache --json, or use it as a library. - Put
$(usage-cache)in your shell prompt too. A failed read still prints a dash and exits 0, so it never breaks the prompt.
Where it came from
Within 60 seconds every caller gets the cached reading and makes no request. When the cache is older, exactly one caller, whoever wins a file lock, calls the endpoint and the rest read the cache. If a refresh is rate-limited, the last good reading is kept and flagged, so a statusline keeps showing a number.
It's unofficial. It reads an undocumented Anthropic endpoint with your own Claude Code login, so it can break whenever that endpoint changes. It isn't affiliated with or endorsed by Anthropic.
Excellent runs on your machine too, beside your agents, and checks their work for itself. excellent.so