ClaudeUsage 1.5.0

Claude Usage Monitor

A terminal dashboard for your Claude subscription read-time usage and service status, tells you if you're on track/ahead/behind of your quotas.

It reads the OAuth token that claude login already stored on your machine, polls Anthropic's usage endpoint, and paints a live TUI with your session/weekly windows, per-model breakdown, extra-usage spend, burn-rate pace, current Claude and GitHub service status, and a blinking alert when Anthropic ships a new model or a major Claude Code feature.

dotnet tool install --global ClaudeUsage
claude-usage

Published on NuGet as a .NET global tool. Under the hood it's still a .NET file-based app — a single ClaudeUsage.cs that declares its own dependencies via #:package directives — so you can also run it straight from source with no build step and no .csproj, see Run from source below.

Requirements

• .NET SDK 10.0 or newer. Check with dotnet --version.
• An authenticated Claude CLI session — run claude login if you haven't. Works on Windows, Linux, and macOS; the credentials are read from wherever the Claude CLI stored them (see How it authenticates).

Install

dotnet tool install --global ClaudeUsage   # install
dotnet tool update --global ClaudeUsage    # upgrade to the latest version
dotnet tool uninstall --global ClaudeUsage # remove

This puts a claude-usage command on your PATH (make sure ~/.dotnet/tools — or %USERPROFILE%\.dotnet\tools on Windows — is on it; the .NET SDK installer usually adds it for you).

Run from source

Clone the repo and run the file directly — no install, no build step:

dotnet run ClaudeUsage.cs

Dependencies (Spectre.Console) are restored automatically on first run.

Usage

claude-usage                 # live dashboard, refreshes every 15 min
claude-usage --once          # print one report and exit
claude-usage --interval 5    # refresh every 5 minutes
claude-usage --dump          # probe raw usage endpoints (debug)
claude-usage --help

Running from source instead of the installed tool? Same flags, just prefix with dotnet run ClaudeUsage.cs -- (the -- separates dotnet run's own arguments from the app's):

dotnet run ClaudeUsage.cs -- --once

Flags

⚠️ --dump prints raw account data — your org UUID, plan, display name, and full usage JSON. Redact it before pasting into a bug report or sharing publicly.

Live-mode keys

• r — refresh now
• a — acknowledge news (stops the blinking)
• q — quit

How it authenticates (unofficial)

How it works

• Auth — reuses the OAuth access token the Claude CLI already stored (env var, file, or macOS Keychain); the token is re-read as the CLI rotates it, so long-running sessions keep working without a restart.
• Rendering — a background fetcher owns the network and publishes immutable view-models; the render loop only paints. The clock, countdown, and keypresses stay responsive even during an in-flight request or its timeout.
• Resilience — the last successful response is cached, so panels paint instantly on startup and survive transient network/API failures with backoff.
• Trends — a small local history is kept to show short-term deltas and burn-rate pace against your window limits.
• Service status — the Claude and GitHub status pages (both Statuspage-hosted, same schema) are polled every 5 minutes without auth. All green collapses to a single line; the moment either reports trouble it opens into a panel with one row per service — degraded components, the active incident, and any scheduled maintenance window.
• News — polled every 30 minutes without auth, from two curated sources: the Claude Platform release notes (new models and API features, published the same day) and the Claude Code What's new weekly digest (major features only; bug fixes and minor releases stay out). The latest Claude Code version comes from npm and is shown but never alerted on. Anything new opens a blinking panel until you press a. The first run only records what's already published, so an install doesn't replay history.

Local state

Cache and history are stored outside the repo, in your platform's local application-data directory (ClaudeUsage\cache.json, history.json, and news.json, the acknowledged-news list):

• Windows — %LOCALAPPDATA%\ClaudeUsage\
• macOS — ~/Library/Application Support/ClaudeUsage/
• Linux — $XDG_DATA_HOME/ClaudeUsage/ (or ~/.local/share/ClaudeUsage/)

Privacy

This tool talks only to api.anthropic.com (usage/profile), status.claude.com and www.githubstatus.com (service status), and platform.claude.com, code.claude.com and registry.npmjs.org (news). All but the first are public pages; no credentials are sent to them. It does not transmit your token or usage data to any third party. Your credentials never leave your machine except as the Authorization header to Anthropic's own API.

Disclaimer

Not affiliated with, endorsed by, or supported by Anthropic. "Claude" is a trademark of Anthropic. Use at your own risk.

License

Released into the public domain under The Unlicense — do whatever you want with it.