claude-usage

claude-usage

Know how much of your Claude.ai plan you've burned — from your terminal, shell prompt, or menu bar.

claude-usage is a tiny cross-platform CLI that reads the Plan Usage numbers from your Claude.ai account (Current session, Weekly all-models, Sonnet, Design) and surfaces them where you actually work: a one-shot status command, a live TUI, a shell-prompt segment, or a system tray icon.

…and a native macOS menu-bar icon that drains and shifts color as you approach the limit:  

Numbers are battery-style: the percentage and bar represent how much capacity is left in each bucket (100% = untouched, 0% = at the plan ceiling). Threshold colors are still decided from raw usage so warn/alert fire at the same place they always did.

$ claude-usage status
Session   █████████░░░░░░░░░░░  49%  (resets in 1h 5m)
Weekly    █████████████████░░░  87%  (resets Sun 3:00 PM)
Sonnet    ████████████████████ 100%
Design    ████████████████████ 100%

Install

macOS

brew install tonydisco/tap/claude-usage

sudo xcode-select -s /Library/Developer/CommandLineTools
brew install tonydisco/tap/claude-usage

Windows

# PowerShell one-liner (recommended)
irm https://raw.githubusercontent.com/tonydisco/claude-usage/main/install.ps1 | iex

# Or via Scoop
scoop bucket add tonydisco https://github.com/tonydisco/scoop-bucket
scoop install claude-usage

The installer drops claude-usage.exe into %LOCALAPPDATA%\claude-usage\bin and adds it to your user PATH. Open a new terminal afterwards.

Linux

curl -fsSL https://raw.githubusercontent.com/tonydisco/claude-usage/main/install.sh | bash

Any platform (from source)

go install github.com/tonydisco/claude-usage/cmd/claude-usage@latest

Binaries are signed and published from GitHub Actions via goreleaser. Source: .github/workflows/release.yml.

Tray / daemon. The macOS release (Homebrew Cask) is a CGO_ENABLED=1 build linking AppKit, and Windows uses pure Win32 syscalls — so claude-usage tray and claude-usage daemon start work out of the box on both macOS and Windows. The Linux release tarball is CGO_ENABLED=0 for clean cross-compilation, which leaves the tray feature stubbed; install from source with the system's GTK/AppIndicator headers to get the panel icon:

# Debian/Ubuntu
sudo apt install libgtk-3-dev libayatana-appindicator3-dev
go install github.com/tonydisco/claude-usage/cmd/claude-usage@latest

Everything else (status, watch, prompt, login, update, welcome, …) works in every build, on every platform.

Quick start

# 1. Authorize — scans your browsers for an existing claude.ai session,
#    or opens claude.ai and auto-detects once you sign in. No copy/paste.
claude-usage login
# (use `claude-usage login --manual` on headless boxes to paste manually)

# 2. Check status
claude-usage status

# 3. Embed in your zsh prompt
PROMPT='%~ $(claude-usage prompt) ❯ '
# → ~/code [51%/13%] ❯

# 4. (optional) Tray icon + background notifications
claude-usage daemon start

# 5. Upgrade later — auto-detects brew / go install
claude-usage update

Run claude-usage welcome anytime to re-print the post-install banner with the full quick-start, update, and link reference.

Features

• Cross-platform single binary — macOS (Intel + Apple Silicon), Windows, Linux. No runtime to install.
• Three frontends in one tool — CLI, live TUI (watch), shell-prompt segment (prompt), and tray icon (daemon).
• Tracks Claude.ai plan usage (Pro / Max), not just Claude Code token costs.
• Secure auth — session cookie is stored in macOS Keychain / Windows Credential Manager via zalando/go-keyring, never written to a plaintext config file.
• Configurable thresholds & notifications — battery-style bands: green below warn_threshold (default 65%), orange between, red at/above alert_threshold (default 90%). Override in ~/.config/claude-usage/config.toml.
• oh-my-zsh plugin included — drop into $ZSH_CUSTOM/plugins/claude-usage and add claude-usage to your plugins=(...).

How is this different from existing tools?

There are several great Claude-related usage trackers already. They mostly target Claude Code's local JSONL files. claude-usage targets the Plan dashboard on claude.ai itself, which is the number that actually decides whether you can keep chatting today.

Pick claude-usage if you live in a terminal and want plan info in your shell prompt, or you need a cross-platform tray icon on Windows/Linux.

Pick ccusage if you mostly use Claude Code from the CLI and care about token cost per project.

Pick Claude-Usage-Tracker if you're macOS-only and want a polished native menu bar app.

Commands

claude-usage --help lists every command. The table below is the full reference, grouped by what you'd use them for.

Authorization

Read usage

Menu-bar / system-tray app

Linux: the release tarball is CGO_ENABLED=0, so tray / daemon start are stubbed there. Build from source (go install github.com/tonydisco/claude-usage/cmd/claude-usage@latest) with libgtk-3-dev + libayatana-appindicator3-dev to get the panel icon.

Configuration

Maintenance & discoverability

Global flags

Configuration

~/.config/claude-usage/config.toml (auto-created on first save). All keys are optional — missing ones fall back to defaults.

poll_interval_seconds = 60      # tray / watch refresh cadence (min 5s)
warn_threshold        = 65      # usage % at which the bar turns orange
alert_threshold       = 90      # usage % at which the bar turns red + fires a notification
notify                = true    # desktop notification when a bucket crosses warn/alert
org_id                = ""      # claude.ai organization UUID; leave empty to auto-detect
last_seen_version     = ""      # written by the welcome banner — leave alone

Set individual keys with claude-usage config set <key> <value>, print the active values with claude-usage config show, or open the file at claude-usage config path.

How it works (and the honest caveat)

Anthropic doesn't publish an API for Claude.ai plan usage. This tool calls the same internal endpoint that the Settings → Usage page in your browser hits, authenticated with the session cookie picked up by login.

claude-usage login reads the sessionKey cookie directly from your installed browsers (Firefox, Safari, Chrome, Edge, Brave, …) via browserutils/kooky. On macOS, reading Chrome cookies asks the OS Keychain for the encryption key — you'll see a one-time "claude-usage wants to access Keychain" prompt; pick Always Allow to silence it. If you'd rather not let the tool read browser storage, use claude-usage login --manual and paste the cookie yourself.

This means:

• Anthropic may change the endpoint shape at any time. When that happens the tool will likely break until I ship a patch. Watch Releases — patches usually land within 24–48h.
• Your session cookie is sensitive (it's a login). claude-usage stores it only in your OS keychain, and only the HTTPS request to claude.ai ever sees it.
• This is not affiliated with or endorsed by Anthropic.

The fetcher is isolated in internal/fetcher so endpoint patches are a single-file change.

Roadmap

• Phase 0 — Endpoint reconnaissance (see samples/usage-response.json)
• Phase 1 — Core CLI (login, status, logout)
• Phase 2 — TUI (watch) + shell prompt + oh-my-zsh plugin
• Phase 3 — Daemon + tray icon + threshold notifications
• Phase 4 — Homebrew tap + install script (Scoop bucket and Apple notarization pending)

Contributing

PRs welcome — especially for:

• Endpoint patches when claude.ai changes things (see internal/fetcher/)
• Linux tray icon polish (Wayland is the hard part)
• Translations of CLI output

Run the test suite with go test ./.... Mock data lives in samples/.

License

MIT — see LICENSE.