claude-usage-bar

macOS menu bar widget that shows your Claude Code rate limit usage in real time.

What it shows

Requirements

• macOS (Apple Silicon / Intel)
• Claude Code v2.1.80+ — rate_limits in statusLine
• Claude Pro / Max / Team — rate limit data requires a subscription

Install

brew tap hwayoungjun/tap
brew install claude-usage-bar

Setup is automatic: ~/.claude/settings.json is configured on install and on every app launch.

git clone https://github.com/hwayoungjun/claude-usage-bar.git
cd claude-usage-bar
go build -o claude-usage-bar .
./claude-usage-bar setup

Uninstall

brew uninstall claude-usage-bar

This removes the LaunchAgent, the statusLine config, and the app data along with the binary.

Usage

restart picks up a new build without hunting for the running process: it unloads a
launchd-managed job so the plist is re-read, signals a copy started by hand, waits for the
single-instance lock to come free, then starts it again. Under brew services it prints the
brew services restart line to run instead.

Auto-start on login

brew services start claude-usage-bar

Or enable Launch at Login from the dropdown menu.

How it works

Claude Code sends rate limit data through the statusLine hook on every assistant message.
This tool captures that data and draws it in the menu bar.

Sessions started from the Claude desktop app are covered too. statusLine never fires for
those — the app runs Claude Code headless and draws its own UI, so there is no terminal status
line to render — so the widget falls back to the usage history the desktop app keeps for its
own meter (~/Library/Application Support/Claude/plan-usage-history.json). That costs no API
call and no credentials, but it only carries percentages, and only about every 15 minutes.

Claude Code (terminal) ──stdin──▶ claude-usage-bar statusline ──▶ usage.json
                                                                     │
                                                                     ▼
Claude desktop app ──▶ plan-usage-history.json ──────────▶ claude-usage-bar (menu bar)

1. Claude Code calls claude-usage-bar statusline after each assistant message.
2. The statusline subcommand parses rate limit data from stdin and writes
   ~/.config/claude-usage-bar/usage.json.
3. The menu bar widget watches usage.json via fsnotify and updates instantly.
4. When the desktop app's history is more recent than the last statusLine report, the widget
   shows that instead, labelled Claude app; reset times carry over from the last statusLine
   report while they are still in the future.

[!NOTE]
Only the 5h session and 7d all-models windows are drawn. The statusLine payload declares
five more — the per-model 7d windows, an OAuth-apps window, a server-labelled model_scoped
list and an extra_usage credit budget — but on the account this could be checked against
every one of them arrived null or absent, so there was nothing to draw. See
internal/statusline for the details.

Development

Dependencies point one way: the composition root wires adapters to the domain, and the domain
knows about neither.

make test

The domain packages carry the tests: usage 98%, session 92%, textwidth 100%, shellquote 100%,
statusline 93%. The file adapters follow at store 79% and install 61%. The systray layer holds
no rules and is not covered.

License

MIT — see LICENSE.

_{This project is not affiliated with Anthropic. Claude and Claude Code are trademarks of Anthropic.}