ClaudeLimitsDocumentation

← Product page

Documentation

Everything ClaudeLimits does, and how to make it yours. It's a single menu-bar app — there's not much to learn, but here it all is.

1 · Install & first launch

ClaudeLimits ships as a regular .app. Move it to /Applications and open it.

It's a small indie build, so the first launch goes through Gatekeeper. If macOS says it can't verify the developer, right-click the app → Open → Open, or allow it from System Settings → Privacy & Security.

Once open, four numbers appear in your menu bar — and that's it. There's no window and no Dock icon; the app is a menu-bar agent (LSUIElement).

2 · Reading the menu-bar numbers

The readout is two lines:

63% 2h   ← 5-hour window
41% 4d   ← weekly window

Each line is percent used followed by time until that window resets. Claude Code limits you on two clocks at once — a rolling 5-hour budget and a weekly one — so the top line is the 5-hour window and the bottom line is the week.

Sometimes the readout shows something other than numbers. Here's what each state looks like:

3 · The usage panel

Left-click the menu-bar icon and a small panel drops open — laid out just like /usage inside Claude Code. It opens instantly, with no fade or delay, and while it's open it updates live: the moment a fresh reply lands from the server, the numbers and bars move on their own.

It's headed Plan usage, with an arrow → on the right that takes you to claude.ai/settings/usage for the full picture. Below the heading are three rows, each one a label, the percent used, the time until that window resets, and a progress bar:

Each progress bar is tinted by load, so a glance tells you how much room is left: it stays neutral while you're comfortable, then shifts yellow, orange, and red as you fill up — the same 50 / 75 / 90% steps as the colour readout.

The third row is per-model, and it reads Opus only or Sonnet only depending on your plan — it surfaces whichever model your plan meters separately, so you won't see both at once.

4 · The menu

Right-click (or ctrl-click) the menu-bar icon to open the menu. (A plain left-click opens the usage panel instead.)

The Auto-refresh in … line is read-only — a greyed-out countdown, not a button. It shows when the OAuth token will be silently refreshed in the background:

All choices are remembered between launches.

About & Permissions… opens a small panel that spells out exactly what the app touches on your Mac — and, just as importantly, what it never touches:

5 · Where the numbers come from

ClaudeLimits reads the numbers straight from your account, the same way Claude Code does. It takes your OAuth token from the Keychain entry Claude Code-credentials and calls https://api.anthropic.com/api/oauth/usage. The result matches what /usage shows inside Claude Code, to the digit — no estimates, no guesswork.

Polled every 10 minutes, because Anthropic rate-limits this endpoint — see Refresh cadence & rate limits below.

6 · Refresh cadence & rate limits

ClaudeLimits refreshes on its own every 10 minutes, not continuously. That's a deliberate choice, and it's worth explaining why — because the same endpoint that makes the numbers exact is also the one Anthropic guards most closely.

Why it isn't instant

The figures come from /api/oauth/usage — the very endpoint Claude Code's own /usage reads. Anthropic strictly rate-limits that endpoint. This is not an account ban or anything to worry about: Claude Code and everything else keep working normally. It's only this one endpoint that gets temporarily throttled if it's polled too eagerly.

We measured it directly. Polling once every 60 seconds, the server reliably starts replying HTTP 429 (rate_limit_error) — its way of saying too often, slow down. When it does, it also returns a Retry-After header of roughly 50–60 minutes: the window you're expected to stay quiet for.

How it backs off

If the server ever does return a 429, ClaudeLimits does the polite thing rather than keep knocking — because knocking only extends the penalty. Specifically, it:

• Honours Retry-After exactly — it pauses for precisely the window the server asked for, then resumes polling on its own.
• Keeps your last good numbers on screen — instead of flashing an error, it holds the most recent figures and shows a small retry in ~Nm until it's allowed back, so the readout never goes blank on you.
• Recovers automatically — once the window passes, normal 10-minute polling picks up again with no action from you.

For comparison, Claude Code's own /usage feels live for the same reason: it caches the last answer rather than hitting the endpoint every second.

“Refresh on open only” — even gentler

If you'd rather produce zero background traffic, there's a toggle for it. Open Settings in the menu and turn on Refresh on open only. Background polling stops completely: the numbers refresh only when you open the panel (left-click the menu-bar icon) — exactly the way /usage behaves inside Claude Code, fetching on demand rather than on a timer.

The same safeguards still apply. Even on open it won't fetch more than once every 10 minutes (open it sooner and you simply see the last cached numbers), and it still honours a Retry-After backoff after a 429. And while the panel is open, it updates live the moment the server's reply lands.

Left: a quiet timer fetches on its own every 10 min. Right: nothing happens until you open the panel, then it pulls the numbers.

7 · View modes & colours

Mono renders the numbers as a normal template glyph — it follows your menu-bar appearance (dark/light) like any other system icon, and stays visually quiet.

Colour tints the percentage by how close you are to the cap, mirroring Claude's own warning steps. The time-to-reset next to it stays a calm grey — so your eye lands on the number that matters, not the clock:

The four steps side by side, the way the percentage actually shifts colour as the window fills:

8 · Tuning

There's almost nothing to tune — the app keeps its handful of settings in standard UserDefaults under its bundle id com.kolocim.claudelimits. You can adjust them from Terminal, then relaunch the app:

# view: "mono" or "color"
defaults write com.kolocim.claudelimits color_mode -bool true

# custom User-Agent for the usage request (advanced)
defaults write com.kolocim.claudelimits user_agent -string "claude-cli/1.0"

9 · Settings

The menu's Settings section holds two toggles:

Both are toggled straight from the menu — no system dialogs, and your choice is remembered between launches.

10 · Privacy

No account, no sign-up, no analytics, no telemetry. Nothing about your usage ever leaves your Mac, with a single exception: the app makes one request to Anthropic's own API (api.anthropic.com) using your existing token — the exact same call Claude Code itself makes. That's the only network traffic it ever produces.

11 · Troubleshooting

The numbers are blank or show —

Claude Code isn't signed in on this Mac, so there's no token in the Keychain. Sign in once and press Refresh.

The numbers stopped updating

You may have been rate-limited for refreshing too often. The app handles this on its own: it waits out the window Anthropic asks for, keeps your last numbers on screen, and resumes its safe 10-minute polling automatically. See Refresh cadence & rate limits.

“App can't be opened” on first launch

Gatekeeper. Right-click the app → Open → Open, or allow it in System Settings → Privacy & Security.