Guide
How Claude Code rate limits actually work
You hit a limit mid-task, Claude tells you to come back at some odd time like 2:14 am, and nothing about it feels predictable. It actually is predictable. Claude Code runs on two clocks, and once you know how they tick you can plan your whole week around them. This guide explains both, plus the tricks that make the limits work for you instead of against you.
The two clocks: session window and weekly cap
Every Claude subscription (Pro and Max) meters Claude Code usage with two separate limits:
- The 5-hour session window. A rolling window that starts when you send your first message and expires 5 hours later. All your usage inside that window draws from one shared pool.
- The weekly cap. A larger allowance that refreshes once a week at a fixed time. On top of it there are separate weekly limits for specific models. Heavy models like Opus or Fable have their own weekly meter that can run out while your overall weekly cap still has room.
You can be blocked by either clock. Most confusion comes from people watching one clock while the other one runs out.
How the 5-hour window really starts
The window does not start on the hour and it does not start when you open the terminal. It starts at your first message. Send your first prompt at 9:14 am and your window runs 9:14 am to 2:14 pm.
Three details that follow from this, and that most people miss:
- Idle time costs nothing. If a window expires while you are away, no new window starts until you send another message. You are never "wasting" windows by not working.
- Continuous work rolls straight into the next window. If you are mid-session when the window expires, your next message opens a fresh window immediately. Long overnight agent runs keep going, they just start drawing from a new pool.
- Unused capacity does not roll over. Each window is independent. Using 4% or 96% of a window makes no difference to the next one.
The weekly cap and the hidden per-model limits
The weekly cap resets once every 7 days at a time set by your billing cycle, not at midnight. Inside the API response that powers the /usage screen there are also per-model weekly limits with their own percentages and reset times. These are easy to miss. It is entirely possible to sit at 50% overall weekly usage while your Fable or Opus weekly meter is at 93%, which means the model you actually care about is nearly gone.
If you use a heavy model for everything, this per-model meter is almost always the limit you hit first. The standard advice holds: use the big model to plan, then hand implementation to cheaper models like Sonnet or Haiku. Your per-model meter will thank you.
When exactly does my limit reset?
Three ways to find out, from quickest to most complete:
- Run /usage inside Claude Code. It shows your current session and weekly percentages with reset times. This is the official source.
- Do the math. Your session resets exactly 5 hours after your first message of the window. If you know when you started, you know when it resets.
- Put it on a calendar. This is what we built AgentCalendar for. It runs locally, reads the session logs Claude Code already writes to your machine, pulls the same usage numbers the /usage screen uses, and draws every session, every window, and every reset on a week view. Codex limits show up on the same calendar if you use both.
npm install -g agentcalendar
agentcalendar # opens http://localhost:4747Three ways to make the limits work for you
1. Anchor your window to your workday
Since the window opens at your first message, a tiny scheduled message early in the morning pins the schedule. Send anything at 8:00 am and your windows for the day become 8 am, 1 pm, and 6 pm. Predictable resets, no more 2:14 am math. People do this with a cron job that sends "ping" to a cheap model. AgentCalendar has this built in as a one-click daily anchor.
2. Queue heavy work for the reset
The reset moment is the best time to start a big job because the whole window is ahead of it. Instead of staying awake for a 3 am reset, queue the job to fire at the exact second the window opens. You sleep, the agent works, and you read the log over coffee. This is the core feature of AgentCalendar: queue a prompt, pick "at next reset", and it launches automatically with a time cap, a git branch lock, and a full audit log.
3. Watch the right meter
Before starting anything large, check two numbers, not one: your session window and the weekly meter for the model you are about to use. A two-hour refactor started with 40 minutes left in the window will die in the middle. The same refactor started right after a reset fits comfortably.
Frequently asked questions
When does the Claude Code 5-hour window start?
It starts at your first message, not at a fixed clock time. If you send your first prompt at 9:14 am, your window runs until 2:14 pm. If you stay quiet after a reset, no new window starts until you send something.
Do unused hours roll over to the next window?
No. Each window is independent. When it resets, you get a fresh allowance, and anything you did not use is gone.
What happens when I hit the weekly limit?
You are blocked until the weekly reset even if your 5-hour window still has room. The weekly limit sits on top of the session window, and there are separate weekly limits for specific models such as Opus and Fable.
How can I see the exact time my limit resets?
Run /usage inside Claude Code for the official numbers. If you want the reset times on an actual calendar together with your Codex limits, a local tool like AgentCalendar reads the same data and draws every window and reset on a week view.
Can I control when my window resets?
Yes, indirectly. Because the window opens at your first message, sending a tiny scheduled message early in the morning anchors the window to your workday. Your resets then land at predictable times instead of the middle of the night.
AgentCalendar is free, open source, and local. Every Claude Code and Codex session, every window, every reset, on a week view. Queue jobs that fire the moment capacity returns.
npm install -g agentcalendar