Claude Code says "usage limit reached"? Here's why, and how to fix it

"Usage limit reached" means you have used up either your rolling 5-hour session budget or your weekly budget, and Claude Code will tell you the exact time it resets. But if that message shows up after ten minutes of work, the limit isn't the real problem - something in your setup is burning through the budget faster than it should, and that part is fixable today.

What "usage limit reached" actually means

Claude Code meters two things at once, and the message doesn't always make clear which one you hit. The first is a five-hour session limit that applies to Pro, Max, Team, and seat-based Enterprise plans - it resets on a rolling window, and the exact reset time is what Claude Code shows you in the lockout message. The second is a weekly limit, tracked separately for Opus versus every other model, so grinding through Sonnet all week doesn't touch your Opus allowance and vice versa.

Both budgets are shared, not per-app: usage on claude.ai, Claude Code, and Claude Desktop all draws from the same underlying pool, according to Claude's help center. If you had a long chat session on the website this morning, that already counted against the same limit Claude Code is about to hit tonight. API key billing works differently - it's pay-as-you-go with no hard stop - so this entire mechanic only applies if you're on a subscription plan, not billing through the API.

Why you can hit it in ten minutes, not five hours

This is the part that actually confuses people, and it's also the part page one of the search results mostly skips: a five-hour window sounds generous until you notice the limit isn't about wall-clock time, it's about how many tokens your session burns inside that window. A session that reads twenty files and writes fifteen diffs carries every one of those tokens into every following message, because Claude Code has no memory between API calls - the whole conversation gets resent, in full, every single turn.

Claude's own support documentation names five specific habits that drain a session's budget fastest, and none of them are exotic:

Two of those are worth a closer look, because "keep CLAUDE.md lean" and "point at files instead of pasting them" sound like style advice until you see what they actually cost.

The gap between "reference a file" and "paste a file"

Take a real, unremarkable file from this project: src/lib/content-pages.ts, 101 lines, nothing bloated about it.

Paste that file into a message and it costs roughly 1,100 tokens - and it doesn't cost that once. It sits in context and gets rebilled as a cache read on every later turn until you /clear, so a ten-message session with that file pasted early pays for it ten times over. Point Claude at the path instead and the cost is the string itself, a few tokens, full stop. Multiply that gap by however many files get pasted into a debugging session instead of referenced, and "five hours of budget" turns into forty minutes without anyone doing anything unusual.

CLAUDE.md is the same mechanic wearing a different hat. This repo's own CLAUDE.md is 1,172 characters, and it imports AGENTS.md - another 1,673 characters - with @AGENTS.md. That import expands in full at the start of every session; nothing about @import makes it lazy-load (see CLAUDE.md best practices for exactly how that mechanic works). Combined, that's roughly 700 tokens loaded before you've typed a word - reasonable for a file this size, but the same arithmetic gets brutal fast once a CLAUDE.md file grows past a couple hundred lines. If you want the actual number for your own file rather than a guess, the token counter will size it for you in one paste.

How to check what's actually driving yours

Before changing anything, find out which budget you're burning and why:

1. Run /usage inside Claude Code and look at whether you're close to the session limit, the weekly limit, or both - the fix is different depending on which one you keep hitting.
2. Check cache_create across a few turns in the same session. It should drop sharply after your first message. If it stays high on every turn with nothing unusual going on, that's not ordinary usage - see the cache token bug guide for the exact signature and how to rule it in or out.
3. Open your CLAUDE.md and count what's always-on versus what only matters sometimes. Anything conditional belongs in a path-scoped rule or a skill instead, not the file that loads every single session.
4. Look back at what you actually pasted into the last session that blew through the limit fast. If it was full files, function bodies, or long logs instead of paths, that's your answer before you look anywhere else.

Is it a bug, or is it your setup?

Most of the time it's setup, but not always - a still-open GitHub issue on the Claude Code repo, filed in January and sitting past 1,400 comments as of this writing, describes hitting the usage limit almost instantly on a Max subscription with minimal actual work done. It hasn't been marked resolved. That volume of comments on one unresolved report means "I barely did anything and got locked out" is a real, reported pattern for some accounts, not just a support-forum myth - so if the checks above come back clean, a metering issue on Anthropic's side is a legitimate next guess, not a cop-out.

| Signal | Normal usage creep | Possibly a bug | | --- | --- | --- | | Time to hit the limit | Gradual - hours of real work, matching what you did | Near-instant, on a fresh session with little or no work done | | /usage pattern | cache_create drops after turn one, cost tracks activity | Flat high cost from message one with nothing to explain it | | What's in context | Pasted files, a large CLAUDE.md, no /clear between tasks | Nothing unusual - a stock session, default setup | | What fixes it | Trim CLAUDE.md, reference paths, clear between tasks, match model to task | Check /usage, update Claude Code, file or follow an existing issue with your numbers |

When the honest answer is "you actually need more budget"

Not every lockout is a setup problem worth chasing. Heavy legitimate use - a long migration, an all-day pairing session, running several subagents in parallel - burns through a real budget honestly, and no amount of trimming a CLAUDE.md changes that math. If your /usage breakdown looks clean (cache behaving normally, no pasted files sitting in context, a lean CLAUDE.md) and you're still hitting the wall on real work, that's a plan-size problem, not a waste problem, and the fix is upgrading or moving spend to API billing, not more optimization.

FAQ

• What does "usage limit reached" actually mean in Claude Code? You've used up either your rolling 5-hour session budget or your weekly budget - both tracked separately, with Opus metered on its own weekly clock apart from every other model. The lockout message tells you which one and when it resets.
• Why do I hit the usage limit almost instantly instead of after hours of work? Almost always one of five documented habits: not clearing between unrelated tasks, using Opus for routine work, pasting full files instead of referencing their paths, an oversized CLAUDE.md, or skipping the plan step before a big change. Check /usage to see which one matches your last session.
• Is the Claude Code usage limit shared with Claude.ai? Yes. Usage on claude.ai, Claude Code, and Claude Desktop all counts against the same pool, according to Claude's help center - a long chat on the website counts against the same budget Claude Code draws from.
• How do I check what's actually using up my limit? Run /usage and watch cache_create across a few turns, check your CLAUDE.md for content that only matters sometimes, and look at whether you pasted full files into the session instead of pointing at their paths.
• Is instantly hitting the usage limit a known bug? It can be. A GitHub issue on the Claude Code repo describing near-instant lockouts on a Max subscription has stayed open past 1,400 comments. If your own /usage output looks clean and you still get locked out fast, that's a legitimate case to suspect a metering issue rather than your own setup.
• Will upgrading my plan fix it? Only if the cause is real usage, not waste. Check your setup first - a lean CLAUDE.md, referenced paths instead of pasted files, and clearing between tasks - and if the limit still comes fast on genuinely heavy work, upgrading or API billing is the honest fix, not another round of trimming.

The setup habits in that grid above are exactly what UsageCut's free scan measures in your own history instead of asking you to guess - run it once and you'll know whether your next lockout is a five-minute fix or a plan you've actually outgrown.

Made by Neo

UsageCut by ClockedCode - not affiliated with Anthropic. The figures on this page are measured on real Claude Code sessions and labeled measured or estimated where it matters.