Claude Code FAQ

Not a daily limit exactly — Claude Code has a 5-hour session window and a 7-day weekly rolling cap. Both are rolling windows, not daily resets. You can't hit "tomorrow's" quota by waiting until midnight — the session window clears 5 hours after you started heavy usage, and the weekly cap rolls off 7 days after you consumed it.

On Claude Pro/Max plans, both limits exist. The session cap is the one most people hit first during a heavy coding session.

Run /usage in any Claude Code session. It shows both meters as percentages:

/usage
# Session (5h): 23%   — resets in ~3h 52m
# Weekly (7d): 67%    — resets in ~2d 14h
# Context: 41%

For passive, always-visible monitoring without having to run a command: Headroom puts both numbers in your macOS menu bar as a live %, updating automatically as you work.

Claude Code stops mid-task with a rate limit error message. There's no warning before it happens — you find out when the limit is already exceeded. Your task context is preserved (you can continue once the limit resets), but any in-flight work is interrupted.

The error looks like: Claude API rate limit exceeded. Please try again in N minutes.

It depends on which limit you hit and when your heavy usage happened:

• Session cap (5h): tokens used more than 5 hours ago start falling off the window. If you did heavy usage at 2pm and hit the cap at 4pm, you'll recover partially starting at 7pm (2pm tokens fall off).
• Weekly cap (7d): tokens older than 7 days start falling off. Recovery is gradual and can take days.

The /usage command shows the time until reset for each window. Headroom's dropdown shows "resets in Xh Ym" countdown for both.

The session limit is a rolling 5-hour window on total tokens. Anthropic hasn't published the exact token ceiling, but in practice it limits how much you can do in any 5-hour period. A heavy session working on a large codebase (lots of file context, long conversations) will hit it faster than light conversational use.

The session limit is measured as a percentage in /usage. 100% = you've hit the ceiling; Claude Code stops until the window partially clears.

The weekly limit is a rolling 7-day window on total tokens across all sessions. It's the cumulative cap — even if you stay under the session limit every day, you can exhaust the weekly cap if you do a lot of work across many days.

Heavy users on Claude Pro plans typically hit the weekly cap first. Claude Max plans have a higher weekly ceiling.

The context window is separate from the rate limits — it's a technical constraint of the AI model. As your conversation with Claude Code gets longer, the context fills. When it's full, Claude Code has to drop earlier messages or you have to run /clear.

Context fill shows up as gradual degradation (Claude "forgets" earlier parts of the conversation) rather than a hard stop. /usage shows context fill as a percentage. See Claude Code context window explained for more detail.

Yes — Headroom is a free macOS menu bar app that shows your session % and weekly % as a live color-coded number, always visible without needing to run any command. It reads the same data source as /usage — no API calls, no credentials, no setup.

You can also read the raw JSON directly:

cat ~/.claude/headroom-usage.json
# {"sessionUsagePct":23.1,"weeklyUsagePct":67.4,"contextUsagePct":41.0,...}

This file is written automatically once Headroom's hook is installed. See how the hook works for shell/tmux integration recipes.

Claude Code (Anthropic's official CLI) doesn't use an API key — it uses your Claude account OAuth credentials, stored in your macOS Keychain. The rate limits you see in /usage are tied to your Claude Pro or Max subscription, not an API usage tier.

This is different from using the Anthropic API directly (which does use API keys and has separate rate limits).

Usually one of three reasons:

• Session cap hit (5h rolling window) — the most common cause during a heavy session. Fix: check /usage, wait for the window to partially clear.
• Weekly cap hit (7d rolling window) — typically happens after several heavy days in a row. Fix: check /usage for the weekly %, consider pausing intensive work for a day.
• Context window full — conversation got too long. Fix: run /clear or /compact to free context.

Headroom shows all three meters in your menu bar so you can see which one is the problem without having to run a command after the fact.