ClaudeLimits Documentation

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.

Drag in, hit the warning on first launch, then right-click → Open to let it through — once only.

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).

For the numbers to appear it reads the token Claude Code already stored in your Keychain — you'll just need Claude Code signed in on this Mac.

On first launch you may see this offer. Claude Code asks for your Keychain password at the start of almost every session, and “Always Allow” doesn't make it stop — ClaudeLimits can fix that. Click Fix it and a Terminal window opens; type your password once and you're done. It's optional, reversible, and the password only ever goes to macOS. See the full step-by-step →

Reading the menu-bar numbers

The readout is two lines, each showing how full a usage window is and how long until it resets.

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.

You see	Means
`63%`	63% of that window's budget is used up
`2h` / `45m` / `4d`	time left until it resets (hours / minutes / days)
`—` or blank	data not available yet (still loading, or no token in the Keychain)

How the time is rounded

The menu-bar time can be shown two ways, switchable under Settings → Reset time:

Mode	What it does
Like Claude Code (default)	Floors to the whole unit, exactly like `/usage` — `1h 50m` left shows as `1h`.
Honest (nearest)	Rounds to the nearest whole unit, both directions — never understated, never inflated (`1d 3h → 1d`, `1d 13h → 2d`, `1h 50m → 2h`, `1h 20m → 1h`).

This affects the menu bar only — the usage panel is always honest. Want both ranks? Turn on Settings → Two units to show 1d 3h / 1h 50m everywhere.

Special states

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

Loading shows dots; no token shows lim/! in red; a 429 keeps the last good numbers and quietly retries.

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:

Row	Means
5-hour limit	The rolling 5-hour budget — the same short window as the top menu-bar line.
Weekly · all models	The weekly budget across every model combined.
Opus only / Sonnet only	The weekly per-model budget. Which one you see depends on your plan (see below).

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.

Times in this panel are always shown as the exact two-rank countdown — 1h 50m, 5d 23h — never floored, never collapsed to a single unit, no matter whether the menu bar shows one rank or two. This is where you get the precise time to each reset.

If the endpoint is throttling (a 429), the panel doesn't go blank. It keeps the last good numbers on screen and shows a small retry in ~Nm until it's allowed to fetch again. See Refresh cadence & rate limits.

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:

Greyed out and unclickable — purely informational. No action needed.

Item	What it does
Refresh	Fetch the latest numbers right now
View	Switch between Mono and Colour — a tick marks the active one
· Launch at login	Start ClaudeLimits automatically with your Mac
· Refresh on open only	Stop background polling; refresh only when you open the panel (see Refresh cadence)
· Reset time	How the menu-bar time rounds — Like Claude Code (floor) or Honest (nearest unit, both directions). The panel is always honest (see How the time is rounded)
· Two units	Show the menu-bar reset time with two ranks (`1d 3h`, `1h 50m`) instead of one. The usage panel always shows two ranks anyway. Off by default
· Auto-refresh in …	Read-only countdown showing when the OAuth token will be silently refreshed — no action needed
About & Permissions…	Shows exactly what the app accesses — Keychain, network, login item — and what it never touches
Fix Keychain password prompts…	Stops Claude Code's repeated Keychain password prompt — fixes every Claude Code key at once via Terminal (see the step-by-step)
Product page ↗	Open the ClaudeLimits product page in your browser
Restart	Relaunch the app
Quit	Stop the app

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:

Only the Keychain, two Anthropic hosts, and an optional login item — never Accessibility, Screen Recording, camera, or microphone.

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.

ClaudeLimits is read-only toward the Keychain: it never writes or updates the token there. If the token needs refreshing it does so in memory for its own request only — Claude Code stays the single writer of the Keychain entry.

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

If the readout shows nothing, Claude Code probably isn't signed in on this Mac (no token in the Keychain). Sign in to Claude Code once and hit Refresh.

Refresh cadence & rate limits

ClaudeLimits refreshes on its own every 10 minutes, not continuously — a deliberate choice worth explaining.

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.

Anthropic doesn't publish the exact budget, so 10 minutes isn't a computed limit, just a comfortably safe margin well under the threshold. Your usage figures change slowly anyway (only as you spend), so a 10-minute cadence never leaves the numbers meaningfully stale.

How it backs off

If the server ever does return a 429, ClaudeLimits does the polite thing — 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.

"Refresh on open only" — even gentler

If you'd rather produce zero background traffic, 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 — exactly the way /usage behaves inside Claude Code.

The same safeguards still apply. Even on open it won't fetch more than once every 10 minutes, and it still honours a Retry-After backoff after a 429.

Every 10 minutes (default)

App polls on its own, in the background.

→

On open only

No background traffic — fetch on click.

63% · 41%

👆

63%2h 41%4d

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

	Every 10 min (default)	On open only
Background polling	Yes, every 10 min	None
When numbers refresh	On its own, plus on open	Only when you open the panel
Network traffic at rest	One request / 10 min	Zero
How fresh the numbers are	Always within 10 min	As of the last time you looked
Min interval between fetches	10 minutes — and `Retry-After` backoff after a 429 — in both modes

Pick On open only if you want the most account-friendly behaviour possible — not a single background request, and no way to trip the throttle.

View modes & colours

Choose between a quiet monochrome readout and a colour-coded one that shifts as your budget fills up.

Mono

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.

One neutral colour for everything — inherits the menu-bar theme.

Colour

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:

Used	Colour
< 50%	blue — plenty left
≥ 50%	yellow — over halfway
≥ 75%	orange — getting close
≥ 90%	red — almost out

Only the percentage takes the colour; the time-to-reset stays a calm grey.

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

# reset-time rounding: "floor" (Like Claude Code) or "honest" (round to nearest)
defaults write com.kolocim.claudelimits gauge_round -string "honest"

# two units (1d 3h) instead of one, in menu bar and panel
defaults write com.kolocim.claudelimits reset_two_units -bool true

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

The usage endpoint is polled every 10 minutes — Anthropic throttles it, and polling too often can get you temporarily blocked, so the interval is fixed at a safe value. See Refresh cadence & rate limits for the details.

Settings

The menu's Settings section holds a few controls, all remembered between launches.

Control	What it does
Launch at login	Start ClaudeLimits automatically with your Mac, so it quietly reappears in the menu bar after every reboot. Off by default.
Refresh on open only	Stop background polling entirely and refresh the numbers only when you open the panel — the most account-friendly mode, with zero background traffic. See Refresh cadence & rate limits for the full picture. Off by default.
Reset time	How the menu-bar countdown rounds: Like Claude Code (floor, matches `/usage`) or Honest (rounds to the nearest unit, both directions — `1d 3h → 1d`, `1h 50m → 2h` — never understated, never inflated). The usage panel is always honest regardless. Defaults to Like Claude Code.
Two units	Show the menu-bar reset time with two ranks (`1d 3h`, `1h 50m`) instead of one. The usage panel always shows two ranks regardless. Off by default.

All toggled straight from the menu — no system dialogs.

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.

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.

macOS keeps asking for my Keychain password

A dialog saying "security wants to access key Claude Code-credentials" pops up — often at the start of almost every new Claude Code session — and clicking Always Allow doesn't make it stop. This is not ClaudeLimits: the requester is the security command-line tool, which Claude Code shells out to in order to read its own token. The prompt repeats because the Keychain entry has no partition list authorising command-line tools, so every security read asks for a password afresh. Clicking Always Allow does not stop it — that only covers GUI apps, not the security CLI; only fixing the partition list does. (And recent Claude Code often stores more than one entry: the main Claude Code-credentials plus suffixed Claude Code-credentials-<hash> duplicates — every one needs the fix.)

ClaudeLimits can fix this for you — all of those entries at once, for a single Keychain-password entry. Four steps:

1
In the ClaudeLimits menu (the menu-bar icon), choose Fix Keychain password prompts…

Refresh⌘R

View

✓ Mono

Color

Settings

Launch at login

Refresh on open only

Auto-refresh in ~4h

About & Permissions…

Fix Keychain password prompts…

Product page ↗

Restart

Quit⌘Q
2
A Terminal window opens with the command already filled in.
3
Type your Keychain password (your Mac login password) once when Terminal asks, then press Return. The password goes only to macOS — the app never sees it.
4
You'll see ✅ Done. Start a new Claude Code session — no more password prompt.

Safe by design: the app does not show its own password dialog and does not collect your password. It just opens Terminal, where the password is entered the normal way (Terminal has a TTY) — so only macOS ever handles it. ClaudeLimits itself also never triggers the original prompt: it reads the token in-process via the Security framework, so a single Always Allow for the app sticks.

Prefer to do it by hand?

Run this once in Terminal — it asks for your Keychain password a single time, then goes quiet. The teamid:XW3238595N part authorises ClaudeLimits (signed with that Apple Developer Team ID); apple-tool:,apple: keeps Claude Code's own access:

security set-generic-password-partition-list \
  -S "apple-tool:,apple:,teamid:XW3238595N" \
  -s "Claude Code-credentials" -a "$USER"

If you have suffixed duplicates, repeat the command for each, swapping the -s service name (e.g. "Claude Code-credentials-…"). The menu button handles all of them in one go.