Claude Code's 5-Hour Session Limit
A rolling usage cap that stops you mid-task. Here's exactly how it works and how to track it before it hits you.
What "session" means here
The "session" limit is not tied to a Claude Code session in the terminal sense (a single claude process). It's a 5-hour rolling window that tracks cumulative token usage across all your requests — whether you open and close Claude Code many times or keep one terminal running all day.
Two common misconceptions:
- It's not "per launch." Closing and reopening Claude Code does not reset the window.
- It's not "after 5 hours of running." It's 5 hours from when you sent your first request, not from when you opened the app.
How the rolling window works
Requests "fall off" the window 5 hours after they were made. So if you made a burst of requests at 10:00am, that usage disappears from the window at 3:00pm — even if you've been making more requests since then.
This means the window is continuously draining and refilling. You don't have to wait for a hard reset; you just have to wait until your oldest in-window requests are older than 5 hours.
How to check your current session usage
Inside Claude Code: run /usage. It shows the session % and when the window resets.
From the terminal (requires Headroom):
jq '{sessionUsagePct, sessionResetSec}' ~/.claude/headroom-usage.json
Example output:
{
"sessionUsagePct": 72.3,
"sessionResetSec": 4820
}
sessionUsagePct is your current position in the window (0–100%). sessionResetSec is seconds until the oldest in-window request falls off — not when the whole window resets, but when you'll next see some capacity freed.
What Headroom shows
CC 72%·41%
The first number is the session %. Color-coded: gray when low, amber at 70%, red at 90%. The dropdown shows the exact % and the reset countdown.
The value of having this in the menu bar (rather than running /usage) is that you see it before you need it. When you're at 72% and starting a big refactor, you know to check whether you'll have enough headroom to finish it — instead of discovering mid-task that you're out.
When you hit the session limit
Claude Code surfaces an error and refuses new requests until the window rolls forward enough to free up capacity. The wait is usually not 5 hours — it's however long until your oldest in-window requests fall off. If you sent a burst of requests 4h50m ago, you're waiting 10 minutes, not 5 hours.
Check sessionResetSec in the JSON for the exact wait time:
jq '.sessionResetSec / 60 | floor | tostring + " minutes"' ~/.claude/headroom-usage.json
The session limit vs the weekly limit
| Limit | Window | Typical wait when hit |
|---|---|---|
| Session | 5 hours | Minutes to ~1h (rolling drain) |
| Weekly | 7 days | Hours to days |
The session limit is the one you'll hit more often during an intense work session. The weekly cap is the one that ruins your week if you don't watch it.
Strategies for staying under the session limit
- Compress context before long tasks. Start a fresh Claude Code process to clear the context window before large operations — shorter contexts = fewer tokens per request.
- Break large tasks into stages. A 90-minute pause between phases means those first-phase tokens fall off before you start the second phase.
- Watch the amber threshold. When Headroom turns amber (70%), you have roughly 30% of the window left. Plan for a natural break point rather than a forced one.
Monitor the session limit always-on
brew install --cask patwalls/tap/headroom
Or download directly. Free, MIT, ~267 KB, zero config, signed + notarized. The session % is in your menu bar at all times.
→ Full Claude Code rate limits guide
→ When does the limit reset?
→ Set up threshold alerts