claude-usage

Prints your Claude plan usage limits (the "Usage" page Anthropic buried in their settings submenu) by calling the claude.ai web API directly.

$ claude-usage
Claude Plan Usage

  Current session       24%   resets in 1h 0m (Sat 17:30)
  Weekly (all)           3%   resets in 2d 14h (Tue 04:59)
  Weekly (Sonnet)        2%   resets in 2d 14h (Tue 05:00)

How it works

It hits GET https://claude.ai/api/organizations/{org_id}/usage, which returns:

{
  "five_hour":        {"utilization": 24.0, "resets_at": "..."},
  "seven_day":        {"utilization": 3.0,  "resets_at": "..."},
  "seven_day_sonnet": {"utilization": 2.0,  "resets_at": "..."},
  "extra_usage":      {"is_enabled": false, ...}
}

Credentials

No manual setup. The tool reads the sessionKey, cf_clearance, and lastActiveOrg cookies live from every Firefox profile's cookies.sqlite (under ~/.mozilla/firefox/*/) and tries each candidate set until one authenticates.

• The live cookie DB is locked by a running Firefox, so each is copied into a private temp dir before being read with sqlite3, then deleted.
• cf_clearance is bound to the browser's User-Agent + IP, so the tool sends the same Firefox User-Agent string.

The sessionKey and cf_clearance cookies expire and rotate. When they go stale, the tool fails with an actionable hint to reopen claude.ai in Firefox and reload the page, which refreshes the cookies. In varlink mode this is the distinct de.profpatsch.ClaudeUsage.StaleCredentials error (carrying message and hint fields).

Why curl, not net/http

Cloudflare fingerprints the TLS ClientHello (JA3/JA4). Go's stdlib net/http has a recognisably non-browser handshake and gets served a 403 Just a moment... challenge even with a valid cf_clearance cookie. curl's handshake passes, so the tool shells out to it. The SQLITE3 and CURL environment variables override the binary paths (set by the nix wrapper).

Build / run

# via nix
nix build .#claude-usage
./result/bin/claude-usage

# directly (sqlite3 and curl must be on PATH)
go run ./users/Profpatsch/claude-usage

Varlink service

The tool can also run as a varlink service that exposes the structured usage data, for consumption by status bars, scripts, etc.

claude-usage --varlink
# listens on unix:/run/user/$UID/de.profpatsch.ClaudeUsage

Interface de.profpatsch.ClaudeUsage with one method GetUsage():

varlinkctl call /run/user/$UID/de.profpatsch.ClaudeUsage \
  de.profpatsch.ClaudeUsage.GetUsage '{}'

Install as a systemd user service:

nix profile install .#claude-usage
cp users/Profpatsch/claude-usage/claude-usage.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now claude-usage.service