Claude Code usage limits: how the 5-hour and weekly windows work
By MohammadMD1383 · Updated
If you use Claude Code with a Claude subscription, every request draws from two allowances: a rolling 5-hour window and a weekly window. This guide explains what each one is, how to check where you are, what happens when you run out, and how to keep a long agentic task from being cut off halfway.
Summary
- Pro, Max, Team and Enterprise plans meter Claude Code usage in a rolling 5-hour window and a weekly (7-day) window. The allowance is shared with Claude chat.
- Some plans also have model-specific limits ("You've hit your Opus limit"). Switching to another model family with
/modelkeeps you working; for the session and weekly limits it doesn't. - Check usage with
/usage, or show it permanently: the status line receivesrate_limits.five_hourandrate_limits.seven_dayafter every response. - When a limit is hit, Claude Code blocks requests until the reset time, unless usage credits are turned on.
- The model itself can't see your limits. Give it that awareness (for example with usage-guard) so it commits and hands off before it is cut off.
The two usage windows
Claude subscriptions include a usage allowance rather than per-token billing. For Claude Code that allowance is measured in two windows at once, and you can be stopped by either:
| Window | How it works | Error when exhausted |
|---|---|---|
| 5-hour (session) | A rolling window. It starts with your first message after the previous window ended and resets 5 hours later. If you are idle when it resets, the next window only starts with your next message. | You've hit your session limit · resets 3:45pm |
| Weekly (7-day) | A longer window that caps total use across the week. It keeps counting across many 5-hour windows. | You've hit your weekly limit · resets Mon 12:00am |
Usage is counted per account, not per session. Several Claude Code sessions in parallel, other devices and Claude chat all draw from the same windows, so a session can find the limit closer than its own work would suggest.
The size of each allowance depends on your plan (Pro, Max, or a Team or Enterprise seat tier) and isn't a fixed number of messages: long contexts and heavy models use it up faster. Check Anthropic's help center for your plan's current terms.
Model-specific limits
Besides the shared session and weekly limits, some plans have limits that apply to one model family only:
You've hit your Opus limit · resets 3:45pm
You've hit your Sonnet limit · resets 3:45pm
These only block requests to that family, so switching to a model outside it with /model keeps you working. The session and weekly limits are shared across all models, so switching models does not restore access after those.
How to check your usage
/usagein Claude Code shows plan usage bars, and on Pro, Max, Team and Enterprise plans a breakdown of what counts against your limits: usage attributed to skills, subagents, plugins and MCP servers, and flags for behaviors such as long context or cache misses. Press d or w to switch between the last 24 hours and 7 days. The breakdown is computed from local history, so it doesn't include other devices.- claude.ai → Settings → Usage shows the same plan limits in the browser.
- A status line or a bar keeps the numbers on screen all the time, which is the only way to notice a fast burn before it becomes a problem. See the next section.
Show limits in your status line
Claude Code sends your status line command a JSON object after every response. For Pro and Max subscribers it includes the two windows, each with used_percentage (0–100) and resets_at (Unix epoch seconds). The fields appear only after the first API response in a session and may be absent, so handle that:
#!/bin/sh
# ~/.claude/statusline.sh: prints e.g. "5h 31% · 7d 41%"
input=$(cat)
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
out=""
[ -n "$five" ] && out="5h $(printf '%.0f' "$five")%"
[ -n "$week" ] && out="${out:+$out · }7d $(printf '%.0f' "$week")%"
echo "${out:-limits: waiting for first response}"
Make it executable and point ~/.claude/settings.json at it:
{
"statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
}
If you'd rather not maintain a script, usage-bar draws the same data as a bar above the prompt, with the context window, colored meters and reset countdowns, and leaves your status line alone. The official status line documentation lists every field.
What happens when you hit a limit
- Claude Code blocks further requests and shows which limit you hit and when it resets.
- If usage credits are turned on for your plan, you can keep working past the limit and the extra use is billed as credits. Run
/usage-creditsto manage them. - In an interactive session signed in with a subscription, recent versions of Claude Code can wait in the open session and continue the interrupted task shortly after the reset.
- For a model-specific limit, switch models with
/model.
None of these help with the work that was in flight when the limit hit. That is the real cost.
Why usage limits hurt agentic coding
Claude Code is agentic: one prompt can turn into dozens of tool calls, edits and test runs. But the model doesn't receive your usage figures, so it plans as if the budget were unlimited. A typical failure looks like this:
- At 92% of the 5-hour window, you ask for an 8-step refactor.
- Claude edits six files, three of them only partly, and runs out mid-edit.
- Nothing is committed, there are no notes, and the code doesn't build. You wait hours for the reset, or hand a confusing workspace to another agent.
A raw percentage is also misleading. 85% with three hours left in the window can be fine, while 70% burning 2% a minute runs out in fifteen minutes. What matters is the projected time left at the current pace.
How to avoid getting cut off
1. Make Claude aware of the limits
usage-guard feeds the limit data to Claude through hooks. It adds no tokens at normal usage. At 75% it only tells Claude where it stands. Past 95% it writes and commits HANDOFF.md, and past 98% it stops starting new work. If the limit hits anyway, a script writes an emergency snapshot of the branch, uncommitted files and open tasks.
2. Commit in small steps
Ask Claude to commit after every finished task. A limit that hits between commits then costs minutes, not the whole change.
3. Keep a hand-off note
A short file with the goal, what's done, what's in progress, next steps and how to verify lets any agent, a teammate or the next session continue immediately. Run /usage-guard:handoff to write one on demand.
4. Keep the context small
Each request carries the conversation's context, so long contexts use the allowance faster. Use /clear when you switch to unrelated work, and /compact with instructions on what to keep when you want continuity. Note that compacting a large context is itself a large request; /clear costs nothing.
5. Match the model to the task
Use a lighter model for routine edits and reserve the heaviest model for hard reasoning. This also helps when you are near a model-specific limit.
6. Time big tasks around resets
If the 5-hour window resets in 20 minutes, it is often better to plan now and start the big change after the reset than to start it at 90%.
FAQ
How long is the Claude Code usage limit?
There are two windows. The session limit uses a rolling 5-hour window, and the weekly limit uses a 7-day window. The error message tells you exactly when the window you hit resets.
Does Claude Code share usage limits with Claude chat?
Yes. On subscription plans the allowance is per account and shared with Claude chat, so usage in claude.ai, on other devices and in other Claude Code sessions counts toward the same windows.
How do I see how much of my Claude Code limit I have left?
Run /usage in Claude Code, check Settings → Usage on claude.ai, or show the rate_limits fields in your status line. The usage-bar plugin shows both windows with reset countdowns above the prompt.
Does switching models help when I hit the limit?
Only for model-specific limits such as the Opus or Sonnet limit. The session and weekly limits are shared across all models, so switching models does not restore access.
Do usage limits apply when I use an API key?
No. Plan usage limits apply to subscriptions. With an Anthropic API key, Amazon Bedrock or Google Vertex AI you pay per token and are subject to that provider's rate and spend limits instead.
Can Claude Code continue automatically after the limit resets?
Recent versions can wait in an open interactive session and continue the interrupted task shortly after the reset. A hand-off file still helps if you want to continue somewhere else or with another agent.
Sources
- Claude Code docs: Manage costs and usage
- Claude Code docs: Error reference (usage limits)
- Claude Code docs: Status line