claude-usage
Your Claude quota, live in the terminal status bar.
Session, weekly, and per-model windows with reset times. The same numbers as /usage, always in view. Optional alerts at 50, 80, and 90 percent: in the terminal, on the desktop, or on your phone.
The line it keeps in your bar:
The AI installs it
The repo ships a machine-readable runbook, AGENTS.md. Paste one line into Claude Code and the agent clones the repo, detects which terminal you're in, wires it up, and verifies its own work.
Paste into Claude Code
Works in any coding agent that can run shell commands. The one step it can't do for you is drag the widget into iTerm2's status bar, and it will tell you when.
Why
You find out you hit your weekly limit when Claude tells you. Mid-task. The number existed the whole time; it was hidden behind a command you have to remember to run.
claude-usage makes remaining quota ambient, like a battery percentage, so you can check before starting something big.
Pick the look you want
iTerm2's component list ships six ready-made entries, each previewed right where you drag it from. What you see is what you get, with nothing to configure afterward. They're shown widest first; choose whichever suits the room your bar has.
Wide · Countdown default
Window labels, percentages, and how long until each window resets, counted down from now. The most informative, and the widest.
Wide · Inline
The same information, but resets as wall-clock times and dates rather than countdowns. Pick this if you'd rather know when than how long.
Medium
Labels and percentages, no reset times, for when resets are noise to you and you just want the numbers.
Compact · Countdown
Drops the labels and the word “Usage”, keeping percentages and bare countdown marks. Roughly a third the width of Wide, and still tells you when things reset.
Compact · Inline
The compact layout with clock times instead of countdowns.
Mini
Three percentages and nothing else, for a bar that's already full.
Every capture above is a real status bar; the green outline marks the component. tmux, WezTerm, kitty, and starship render the same line, and pick their width the same way.
How it works
Your existing login
Reads the Claude Code OAuth token already on your machine: env var, macOS Keychain, or ~/.claude/.credentials.json. It never refreshes the token, and the token goes nowhere except api.anthropic.com.
The official endpoint
Calls the same endpoint the /usage screen reads, so you get the real remaining percentage per window, not an estimate reconstructed from token logs.
One shared cache
One on-disk cache feeds every terminal at once, 60 seconds by default, tunable with CLAUDE_USAGE_TTL. Offline shows your last good numbers marked ✳~, an expired login says so, and display modes always exit 0, so your bar never breaks.
One readable file
The core is about 1,500 lines of stdlib-only Python with zero dependencies and 209 tests, MIT licensed. You can read the whole thing before trusting it near your credentials.
Get an alert before it runs out
Optional. The bar already polls, so the alerts ride on that: one notification per window each time it crosses 50, 80, or 90 percent, then silence until the window resets. No daemon and no extra process. The check runs inside the refresh your status bar already does.
Four channels, any mix
Your terminal's own notification (iTerm2, WezTerm, kitty, ghostty), a macOS notification, a toast inside herdr, or a push to your phone through the free ntfy app on iOS and Android. Pick any mix. ntfy pushes go to HTTPS servers only, and Enterprise subscriptions cannot use ntfy. The local channels still work there.
Your levels
The default is 50, 80, and 90 percent. minimal is 90 only, early adds 25 and 75, or list your own percentages. It watches the session, the week, and every per-model week such as Fable.
One file, one test
Settings live in ~/.config/claude-usage/config.json. Run claude-usage --notify-test to fire a test on every channel and see which ones arrived. A notification carries only the window name, the percentage, and the time to reset.
Install by hand
Three commands, then wire up your terminal with the per-terminal guides.
| iTerm2 | Native status bar component via the Python API. |
|---|---|
| tmux | TPM plugin: set -g @plugin 'Tatendaz/claude-usage', then a #{claude_usage} placeholder. |
| WezTerm | One require in wezterm.lua renders it in the right status area. |
| kitty | Tab bar integration (experimental). |
| herdr | Tab bar command slot, plus an in-app toast channel for the alerts. |
| starship, zsh | Prompt segment, or Claude Code's own statusline. Any bar that can run a command works. |