clusage

README

clusage

A terminal UI (Go + Bubble Tea) for watching your Claude Code rate limit windows. It shows how much of each limit you have used, when each one resets, and how the usage moved over the last hours or days.

  Now    History    Tokens    Config    cron 30 4,10,16 * * 1-4

▸ 5h        █████████████████████████████████████████████████████████░░░░░  92%
    ● allowed_warning   resets Mon 19:19 (in 2h0m)

  7d        █████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  41%
    ● allowed   resets Thu 15:19 (in 70h0m)

  7d-opus   ███████████████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░  63%
    ● allowed

read 20m0s ago  ·  claude-opus-5

How it works

The Anthropic API reports your remaining budget in anthropic-ratelimit-* response headers. There is no endpoint that returns them on their own, so clusage makes the smallest possible inference call (one input token, one output token) and reads the headers off the response.

Every reading goes into SQLite, which is what the history graphs draw from.

Each probe call also reports what it cost, so clusage records its own token spend. The Tokens tab shows that spend, so the price of the monitoring is visible next to the limits it monitors.

Install

Homebrew (macOS / Linux)

brew install wolffshots/tap/clusage

Builds from source (Go is installed as a build-only dependency) via wolffshots/homebrew-tap, so it works on Intel and Apple silicon Macs and on Linux, with no Gatekeeper quarantine step.

Prebuilt binaries

Download the binary for your platform from the latest release:

Platform	Asset
Linux x86-64	clusage_<version>_linux_amd64
Windows x86-64	clusage_<version>_windows_amd64.exe
macOS (Apple silicon)	clusage_<version>_darwin_arm64

On Linux/macOS, make it executable and check it runs:

chmod +x clusage_*          # the file you downloaded
./clusage_* --version

macOS binaries are unsigned, so the first launch is blocked by Gatekeeper. Right-click then Open, or clear the quarantine flag with xattr -d com.apple.quarantine clusage_*_darwin_arm64. To verify a download, run sha256sum -c checksums.txt (Linux) or shasum -a 256 -c checksums.txt (macOS).

From source

Go 1.25 or later is required.

go install github.com/wolffshots/clusage@latest

That puts the binary in $(go env GOPATH)/bin. From a checkout, go build -o clusage . builds it in place.

Both report clusage dev rather than a version number. The version is injected by the release build, and go install passes no linker flags. Use Homebrew or a release binary if you want --version to name the release.

Platform support

The keychain path is macOS only. clusage setup shells out to the security command, which does not exist on Linux or Windows. Set CLAUDE_CODE_OAUTH_TOKEN in the environment to skip the keychain on those platforms. Everything else works on all three.

Setup

Store your Claude Code OAuth token once:

clusage setup

The token goes into the login keychain under the service name clusage. The prompt hides what you type. CLAUDE_CODE_OAUTH_TOKEN takes priority over the keychain when it is set.

Run

clusage             # open the TUI
clusage tui         # the same thing, named explicitly
clusage usage       # print one line per window and exit
clusage --version   # print the version and exit

The TUI opens on the last stored reading, so it shows numbers before it calls the API. Press r for a fresh reading.

Keys

Key	Action
1 2 3 4	Now, History, Tokens, Config tab
r	Fetch a reading now
a	Pause or resume the scheduled fetch
tab	Select the next limit window
s	Cycle the history and token span (6h, 24h, 7d, 30d)
?	Toggle the full help
q	Quit

Tabs

Now draws a gauge per limit window with its status and reset time. The color tracks load: green under 60%, amber under 85%, red at or above 85%.

History graphs the selected window over the chosen span, with a sparkline per window underneath for comparison. The scale is fixed at 0 to 100% rather than autoscaled, because a week that sat between 40% and 42% would otherwise render as a crisis.

Tokens graphs what clusage spent on its own probe calls: a cumulative total over the chosen span, a per-call sparkline, and the breakdown into input, output, cache write and cache read. The all-time total is not limited by the span.

The cache rows read 0 in normal use. Prompt caching needs a prefix of about 1024 tokens, and a probe call is around 15 tokens, so nothing upstream will cache it. The rows are recorded anyway, because they come from the response usage block and cost nothing to keep. There is no cache header on the response; the body is the only place these counts appear.

Config shows the effective settings, whether the schedule parses, and when the next scheduled fetch lands.

One-shot output

clusage usage prints the same numbers as plain text and exits.

clusage usage             # uses the cached reading if it is fresh enough
clusage usage -force      # ignore the cache and call the API
clusage usage -verbose    # also print every header and the token cost
clusage usage -model claude-sonnet-5
clusage usage -threshold 15

Flag defaults come from config.json, so a flag is only needed to override the configured value for one run.

Config

Clusage writes config.json on first run, at ~/.config/clusage/config.json (or under XDG_CONFIG_HOME when that is set). The SQLite file sits beside it as clusage.db.

{
  "model": "claude-opus-5",
  "threshold_minutes": 5,
  "fetch_cron": "*/15 * * * *",
  "history_hours": 168
}

Field	Meaning
model	Which model to ping. Cheaper models report the same headers.
threshold_minutes	How long clusage usage reuses a cached reading.
fetch_cron	Schedule for the automatic fetch. Empty disables it.
history_hours	How far back the history graphs may read.

Edit the file and restart to pick up a change.

Scheduled fetches

fetch_cron takes a standard 5-field cron expression:

minute  hour  day-of-month  month  day-of-week

Each field accepts *, a number, a range (9-17), a list (4,10,16), and a step (*/15, 9-17/2). Day-of-week runs 0 to 6 from Sunday, and accepts 7 for Sunday as well.

Separate several expressions with ;. One expression cannot always cover a schedule, so this is how you get a fetch at 09:05 and 18:35 but not at 09:35.

fetch_cron value	Fires
*/15 * * * *	Every 15 minutes
0 9-17 * * 1-5	Hourly, weekday work hours
30 4,10,16 * * 1-4	04:30, 10:30 and 16:30, Monday to Thursday
5 9 * * *;35 18 * * *	09:05 and 18:35
An empty string	Never. Auto-fetch is off

The tab bar shows the active schedule, and marks the last scheduled fetch with ✓ or ✗. A scheduled fetch that fails leaves the last good reading on screen, so the display never blanks while you are away from it.

Two limits worth knowing:

• The schedule only runs while the TUI is open. Nothing accumulates in the background, so history is sparse until clusage has been open a few times.
• day-of-month and day-of-week are ANDed. Standard cron ORs them when both are restricted. Avoid restricting both in one expression.

An expression that does not parse disables the auto-fetch instead of firing at the wrong time. The Config tab flags it in red.

Development

go test ./...     # unit tests, plus a full render of every tab at 96x32
go vet ./...

TestRenderTabs drives the model through Update and logs each tab, so go test -run TestRenderTabs -v . prints the whole UI without a terminal.

Releasing

Pushing a v* tag runs .github/workflows/release.yml, which tests, cross-builds for Linux, Windows and macOS, and creates a GitHub release with the binaries and a checksums.txt.

git tag -a v0.1.1 -m "clusage v0.1.1"
git push origin v0.1.1

The build injects the tag into main.version with -ldflags "-X main.version=<tag>", so clusage --version reports it.

Then bump the Homebrew formula in wolffshots/homebrew-tap. Point url at the new tag and update sha256:

curl -fL https://github.com/wolffshots/clusage/archive/refs/tags/v0.1.1.tar.gz | shasum -a 256

Two traps in that one command:

• Keep -f. Without it, curl prints the 404 body and exits 0, so you hash GitHub's error page. The result is 64 valid hex characters, and brew style accepts it. The formula then fails for every user.
• Hash that exact URL. gh api repos/OWNER/REPO/tarball/TAG returns a different byte stream with a different hash, so a hash taken from it will not match what Homebrew downloads.

Verify before pushing the tap, which catches both:

brew style Formula/clusage.rb
brew install --build-from-source wolffshots/tap/clusage
brew test wolffshots/tap/clusage

Credits

Styling follows wolffshots/fftui. The cron matcher started life in a sibling project.

License

MIT