Claude Code rate limits: how the session cap and weekly cap work

Claude Code has two rate limits that can stop your work cold, with no warning. Both come from Anthropic's API infrastructure — not from your machine, not from the app. Here's exactly how they work.

The two limits

Limit	Window	What it counts	When it resets
Session cap	5 hours	Total tokens in any rolling 5-hour window	Rolling — oldest tokens fall off continuously
Weekly cap	7 days	Total tokens across all sessions in a rolling 7-day window	Rolling — oldest sessions fall off continuously

Both are rolling windows, not reset-at-midnight counters. If you hit the session cap at 3pm, you can't just wait until midnight — you have to wait until the tokens from 5 hours ago fall off. The exact reset time depends on when you started the heavy usage.

What happens when you hit a limit

Claude Code stops mid-task with a rate limit error. There's no soft warning, no "you're getting close" message. You find out when it's already too late to save the current task context.

The error message looks like:

Claude API rate limit exceeded. Please try again in N minutes.

At that point your options are:

Wait for the rolling window to partially clear (session: up to 5h; weekly: up to 7d)
Switch API keys if you have multiple Claude plans
Accept the interruption and restart the task

How to see your current usage

Claude Code has a built-in /usage command that shows both meters:

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

But /usage is reactive — you have to remember to run it. If you're deep in a task and close to the limit, you'll likely forget.

Where these numbers come from: The rate-limit percentages come directly from Anthropic's API — the same source as the /usage command. Claude Code receives them with every API response and renders them in its terminal status line. They're the authoritative numbers, not estimates.

The patterns that hit limits fastest

Not all Claude Code usage is equal. These patterns consume tokens much faster than conversational use:

Large codebase context — loading a whole repo into context on each message multiplies usage
Long back-and-forth debugging — each turn re-sends the full conversation history
Image-heavy sessions — screenshots and diagrams cost significantly more than text
Agentic loops — multiple tool calls per turn, each carrying the full context

A session that would normally last all day can hit the 5-hour cap in 2-3 hours if you're doing heavy agentic work on a large codebase.

Monitoring limits passively with Headroom

Headroom puts both meters in the macOS menu bar as a color-coded live percentage:

CC 23%·67%    ← always visible, no click needed

Color logic:

Green — below 70%: you're fine
Amber — 70–90%: heads up, approaching the limit
Red — above 90%: save your work, stop heavy usage

The dropdown shows exact percentages, reset countdowns (e.g., "resets in 2h 14m"), your active model, session cost, and context window fill. You see it change as you work — so the limit stops being a surprise.

How Headroom reads the numbers

Headroom uses Claude Code's own statusLineHook mechanism. Claude Code writes a JSON file to ~/.claude/headroom-usage.json every time it updates — the same data source as /usage. Headroom reads that file. No API calls, no credentials needed.

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

If you want to use this data in your own tooling — a shell prompt that shows session usage, a script that alerts at 80% — the JSON file is right there. See the hook docs for the full schema and recipes.

Headroom shows session % and weekly % in your menu bar — color-coded, always visible, zero config. Free native macOS app.
Download Headroom — free

brew install --cask patwalls/tap/headroom