Claude Quota Puts Your Claude Code Usage Limits in the macOS Menu Bar

Anyone who runs Claude Code heavily has hit the wall: you are deep in a refactor, you fire off another request, and the model tells you the 5-hour window is exhausted. There is no warning, no dashboard glancing back at you. You find out at the worst possible moment. claude-quota, a small SwiftBar plugin from developer Grzegorz Raczek at Unit8, attacks exactly that gap by parking a live quota gauge in the macOS menu bar.

The problem it solves

Claude Code enforces usage limits on more than one axis. There is a rolling 5-hour window, a weekly cap that acts as the harder ceiling, and on some plans per-model windows on top of that. Claude Code exposes all of this through an internal /usage screen, but you have to stop and ask for it. The information is reactive, not ambient. For someone juggling a personal account and a work account, the mental accounting gets worse, because each config directory carries its own separate limits.

claude-quota collapses that into something you can read without breaking focus. Each account gets one bar in the menu bar. The bar fills as you burn the current 5-hour window and shifts color along the way: green, then orange at 70 percent, then red at 90. Once the window is fully spent, the bar swaps the percentage for a countdown to reset, so 4:28 tells you how long until you can resume. Hit the weekly cap and the bar turns black with a longer countdown like 2D, a visual signal that this is the limit that actually matters regardless of what the 5-hour number says.

The dropdown carries the detail the bars compress away: 5-hour and weekly windows, per-model windows where the plan reports them, any extra-usage credits, and the specific reset times. It refreshes every five minutes, a cadence baked into the SwiftBar filename convention, and there is a manual "Refresh now" entry for when you want an immediate read.

How it actually works

The mechanism is the interesting part, and the author is candid about its trade-offs. The plugin reads your Claude Code OAuth token from the macOS Keychain and calls the same usage endpoint that Claude Code's own /usage screen hits. There is no scraping, no password handling, and no third-party service sitting between you and Anthropic. The first refresh triggers a Keychain permission dialog, where you click "Always Allow."

Crucially, the Keychain access is read-only. The plugin never refreshes or rewrites the token, which means it cannot accidentally log you out of Claude Code, a real risk if it were touching credentials more aggressively. The honest caveat is printed right in the README: the usage endpoint is internal to Claude Code and undocumented, so a future Claude Code update could break it and require a patch. That is the cost of building on an unofficial surface, and naming it openly is the right call rather than pretending the integration is stable forever.

Multiple accounts, handled

The multi-account support is the feature that signals the tool was built by someone living the problem. By default it auto-discovers accounts, scanning for every ~/.claude and ~/.claude-* config directory that has a Claude Code Keychain entry and giving each one a bar labeled by the directory suffix, so ~/.claude-work becomes W. A single discovered account drops the letter and just shows the bar.

If you drive several accounts through CLAUDE_CONFIG_DIR, a common pattern via shell functions like claude() { CLAUDE_CONFIG_DIR="$HOME/.claude-work" command claude "$@"; }, you can pin and rename them in ~/.config/claude-quota/accounts, one path and label per line. Accounts you would rather not see in the menu bar can be hidden from the dropdown while keeping their detail available, or listed in ~/.config/claude-quota/hidden. A stale token from a disused account surfaces as a ⚠ and recovers on the next cycle after you run that CLI once.

Where this fits

Installation is a one-line curl piped to bash, or a git clone and ./install.sh, and either path pulls in SwiftBar through Homebrew if it is missing. macOS and Homebrew are the only hard requirements. Uninstalling means deleting a single claude-quota.5m.py file from the SwiftBar plugin folder, which tells you how thin the whole thing is.

That thinness is the point. claude-quota is not a venture, it is a sharp utility filling a hole the official client leaves open, and it belongs to a small but growing class of community tooling that orbits AI coding assistants now that those assistants have metered, consequential limits. As more developers structure their day around a finite usage budget, ambient visibility into that budget stops being a nicety. The skeptical read is that this is the kind of gap a vendor eventually closes itself, and a tool built on an undocumented endpoint lives on borrowed time. The optimistic read is that it is genuinely useful today, costs nothing, and cannot lock you out. Both can be true. The source is on GitHub for anyone who wants to read exactly what touches their Keychain before they trust it, which, for a tool that reads your auth token, is the only sensible way to adopt it.