Matt Waite
Tools
usage-cacheLater

One usage read for every statusline.

A shared, cached read of your Claude plan usage. However many statuslines, shells and meters you run, together they make one request per interval.

npm i -g @excellent-so/usage-cachenpm

FreeMITNo dependenciesUnofficial

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.

zsh
~/appclaude34% (5h) · wk 61%
~/apiclaude34% (5h) · wk 61%
~/siteclaude34% (5h) · wk 61%

Three sessions, one read of the endpoint a minute.

What you get

  1. 01

    One request per interval

    The endpoint limits each token. Every client reads one shared cache, and only one of them asks the endpoint.

  2. 02

    A number through a 429

    If a refresh is rate-limited, the last good reading stays, flagged, so your statusline keeps showing a number.

  3. 03

    Safe in a prompt

    It always exits 0, and prints a dash when it has nothing, so it never breaks a shell prompt.

  4. 04

    Your token stays put

    Read from the Keychain or ~/.claude, sent only to api.anthropic.com, and never logged, stored or refreshed.

01

Single flight

Within 60 seconds every caller gets the cached reading and makes no request. When the cache is stale, whoever wins an atomic file lock reads the endpoint, and the rest wait briefly and read the cache.

statuslinestatuslinedev shellmenu bar
usage.jsonshared cache
api.anthropic.com1 request / 60 s
02

A library too

readUsage() returns the 5-hour, weekly and per-model figures, the hottest of them, and whether the reading is stale or rate-limited.

node
const { readUsage } = require("@excellent-so/usage-cache");

const res = await readUsage();
// {
//   ok: true,
//   quota: { fiveHour, sevenDay, scoped: [...] },
//   binding: { scope, label, pct, resetsAt },
//   source: "network" | "cache" | "cache-wait",
//   stale: false,
//   rateLimited: false,
// }

How it works

  1. 1

    Install it

    npm i -g @excellent-so/usage-cache
  2. 2

    Try it

    usage-cache --statusline
# 34% (5h) · wk 61%
  3. 3

    Use it everywhere

    // ~/.claude/settings.json
{ "statusLine": { "type": "command",
  "command": "usage-cache --statusline" } }

Details

Needs
Node 18, and Claude Code signed in on the same machine
Cache
One JSON file in ~/.cache, written atomically
Network
One read-only GET to api.anthropic.com, at most once an interval
Dependencies
None
License
MIT

Why I made it

However many status lines are open, it’s one request per interval.

Matt Waite

Try usage-cache.

Free and MIT licensed. Coming soon: the code goes public at launch.

npm i -g @excellent-so/usage-cachenpm