“You’ve hit your session limit” stops a Claude Code session mid-task, and the message alone doesn’t tell you much: not when it resets, not why this session burned through the window faster than yesterday’s, not whether switching models will help. It won’t — usage limits on Pro, Max, Team, and Enterprise plans are shared across every model, so /model doesn’t get you out of a wall you’ve already hit.
Anthropic doesn’t publish the exact prompt-count math behind these limits, which is exactly why a small industry of blog posts has sprung up trying to reverse-engineer it, mostly repeating each other’s estimates. This guide sticks to what Anthropic has actually documented — how the two limit layers work, what changed on May 6, 2026, how to read /usage and /insights, and the specific, official tactics for staying under the ceiling — and flags community estimates as estimates where the numbers aren’t official.
The two-layer system
Claude Code usage on a subscription plan (Pro, Max, Team, Enterprise) is metered by two overlapping windows, not one:
- A 5-hour rolling window. It starts with your first message and renews five hours later — not at a fixed clock time. Start a session at 2 PM, and your window resets at 7 PM regardless of what the wall clock says.
- A weekly cap on top of it. Two weekly limits actually run in parallel: one across all models, one for Sonnet specifically. Both reset at a fixed time assigned to your account, which you can see in Settings → Usage on claude.ai.
Hitting the 5-hour wall just means “wait for the window to renew.” Hitting the weekly wall is worse — there’s no faster reset available short of adding usage credits or upgrading your plan.
Both limits are shared across Claude chat, Claude Code, and Cowork on the same account. A long afternoon in claude.ai chat eats into the same budget as your Claude Code session that evening — they draw from one pool, not separate ones.
On Team and Enterprise plans, the mechanism is the same two-window shape, but the allowance is per-seat and depends on whether you’re on a Standard or Premium seat, and it’s shared with Cowork too.
What actually counts against the limit
A frequent source of confusion: these are usage-window limits, not dollar limits. On Pro and Max, /usage shows a “Total cost” figure for the current session, but that number is computed locally from token counts at standard list rates for reference — it isn’t what determines whether you hit the wall, and it isn’t your bill. What determines the wall is the underlying token consumption against your plan’s window, which Anthropic doesn’t expose as a raw number on subscription plans.
That’s also why community write-ups describe the limits in ranges rather than exact figures — outlets tracking this have published estimates like roughly 10–45 prompts per 5-hour window on Pro and roughly 200–900 on Max 20x, with weekly Sonnet-hour ranges alongside them. Treat numbers like that as directional, not contractual — they vary by prompt length, files read, tool calls made, and model used, and Anthropic has never confirmed a formula publicly.
May 6, 2026: the limits doubled, and peak-hour throttling went away
If you’re reading an article about Claude Code limits published before mid-2026, some of it is now wrong. At the Code with Claude conference in San Francisco on May 6, 2026, Anthropic announced, effective immediately:
| Change | Detail |
|---|---|
| 5-hour limits | Permanently doubled for Pro, Max, Team, and seat-based Enterprise plans |
| Peak-hour throttling | Removed. Pro and Max accounts previously saw reduced 5-hour limits during weekday US daytime hours; that reduction no longer applies |
| Opus API limits | Materially raised for API customers (reported as roughly a 1500% jump in Tier 1 input tokens per minute) |
| Weekly caps | Left unchanged in this announcement |
The change was backed by a compute deal announced the same day: Anthropic gained the full capacity of SpaceX’s Colossus 1 data center in Memphis — over 300 megawatts and 220,000+ NVIDIA GPUs — which is the concrete reason the doubling was framed as permanent rather than a temporary promotion.
There was a second, smaller event worth knowing about if you’re troubleshooting an unexplained fast burn from around that period: in mid-June 2026, Anthropic reset 5-hour and weekly limits for all Pro and Max users after identifying a bug that caused some Claude Code sessions to spawn excessive parallel subagents, consuming usage far faster than the visible activity implied. If you hit a wall unusually fast on an old Claude Code build around that window, that bug — not your workflow — was probably why.
Net effect for 2026: if a blog post, forum comment, or your own mental model still assumes pre-May limits or peak-hour throttling, it’s stale. Current Pro/Max/Team/seat-based Enterprise limits are roughly double what they were in early 2026, and there’s no time-of-day penalty anymore.
Reading your own usage: /usage and /insights
Two commands answer two different questions.
/usage — where you stand right now
Total cost: $0.55
Total duration (API): 6m 20s
Total duration (wall): 6h 33m 10s
Total code changes: 0 lines added, 0 lines removed
Usage by model:
claude-sonnet-4-6: 1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)That “Session” block is the same for everyone, API and subscription alike, but the cost figure only matters for API billing — Pro/Max subscribers have usage included in the plan, so the dollar number is informational, not a bill. On a Pro, Max, Team, or Enterprise plan, /usage also shows a plan usage breakdown beneath it:
- Attribution — the percentage of recent usage attributed to skills, subagents, plugins, and individual MCP servers, so you can see if one noisy MCP server or an over-eager subagent pattern is the actual driver.
- Behavior flags — flags like “long context” or “cache misses” whenever one of them accounts for 10%+ of recent usage, each with a tip attached for reducing it.
Press d/w to toggle between the last 24 hours and the last 7 days. These figures are local to the machine you’re running on — usage from other devices or claude.ai chat isn’t folded in, even though it draws from the same underlying limit.
If the usage endpoint itself is rate-limited (it happens), /usage falls back to the last snapshot fetched within the past 60 minutes and labels it Showing last-known usage; press r to retry.
/insights — how you work, not how much you spent
/insights is a different tool entirely: it analyzes up to 200 recent local sessions and writes an HTML report (~/.claude/usage-data/report.html) covering what you actually worked on, friction points (misunderstood requests, buggy first attempts), and suggestions for using Claude Code more effectively. It runs on any plan, including API, and the tokens it consumes count against your normal limit like any other session.
Why a session burns through usage faster than the visible work suggests
This is the part most limit-explainer posts skip, and it’s usually the real answer to “why did I run out so fast today”:
- Long context compounds. Claude Code resends your full conversation with every request. A one-line question late in an all-day session still carries the whole conversation’s weight, even with prompt caching applied.
- Cache misses reprocess everything. The prompt cache lifetime is one hour on a subscription plan, but it drops to five minutes the moment you’re drawing on usage credits (or by default on an API key/cloud provider). Step away for a coffee past that window and your next message reprocesses full context at full price.
ENABLE_PROMPT_CACHING_1H=1keeps the one-hour lifetime even while on usage credits. - Scheduled tasks fire while you’re not looking. A scheduled task sends your full context on every interval, session idle or not.
- Cross-session messages wake an idle session. If another session sends you a message, an idle session treats delivery as a new turn — full context, full cost. Set
crossSessionInboundtoholdinsettings.jsonif you’d rather batch those instead of paying for each one as it lands. - Every active agent teammate keeps burning tokens until it exits. More on this below — it’s the single biggest multiplier most people don’t account for.
- Compaction itself is expensive.
/compacthas to read the whole conversation it’s about to summarize, so compacting a large context is a large request in its own right./clear, by contrast, costs nothing — it just discards.
Agent teams: the ~7x multiplier
Agent teams spawn multiple Claude Code instances, each maintaining its own full context window. Anthropic’s own guidance states that agent teams use roughly 7x more tokens than a standard session when teammates run in plan mode, because token usage scales with team size, not with the amount of visible output. A three-person team that “just planned an approach” can consume more of your window than a full solo debugging session.
Practical guardrails if you use agent teams at all:
- Default teammates to Sonnet — it’s the balance point for coordination tasks, not Opus.
- Keep teams small; cost is roughly proportional to headcount.
- Keep spawn prompts short. Teammates auto-load CLAUDE.md, MCP servers, and skills, so anything you add on top of that starts every teammate’s context bigger.
- Shut teammates down the moment their piece is done — an idle teammate keeps consuming tokens until it exits or the session ends.
Agent teams are opt-in (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), which is worth knowing if you’re trying to figure out why one project burns through its weekly limit far faster than another with a similar workload — check whether agent teams are quietly enabled there.
The official tactics for staying under the ceiling
In rough order of impact, per Anthropic’s own guidance:
- Clear between unrelated tasks.
/clearstarts fresh at zero cost; stale context otherwise gets resent on every message. Use/renamebefore clearing so you can find the session again, then/resumeto return to it later. - Match the model to the task. Sonnet handles most coding work; reserve Opus for genuinely hard architectural or multi-step reasoning problems. Set
model: haikuon simple subagent tasks in your subagent config. - Cut MCP overhead. MCP tool definitions are deferred by default — only names enter context until a tool is actually used — but CLI tools (
gh,aws,gcloud) are still cheaper than an MCP server because they add zero per-tool listing cost. Run/mcpand disable anything not in active use; run/contextto see what’s actually eating space. - Move workflow instructions out of CLAUDE.md and into skills. CLAUDE.md loads at session start and after every compaction. A 3,000-token CLAUDE.md compacted three times is 12,000 tokens before any code gets written. Skills load only when invoked. Anthropic’s own recommendation is to keep CLAUDE.md under ~200 lines.
- Let hooks pre-filter noisy tool output before Claude sees it. A
PreToolUsehook that greps a test run down to just theFAIL/ERRORlines can turn a 10,000-line log into a few hundred tokens, automatically, every time. - Use plan mode before big changes. Shift+Tab into plan mode so Claude proposes an approach before touching files — this prevents the expensive rework that follows an initial wrong direction, which is a much larger token cost than the plan itself.
- Course-correct immediately, don’t let it compound. Press Escape the moment Claude drifts off course;
/rewind(or double-tap Escape) restores a previous checkpoint instead of paying to argue your way back. - Watch your context live. Run
/usageon demand, or configure your statusline to show context-window usage continuously instead of checking after the fact.
When you actually hit the wall
The message you see tells you which ceiling you hit, and they mean different things:
- “You’ve hit your session limit” / “You’ve hit your weekly limit” — the seat-based subscription window described above. Shared across every model, so switching models doesn’t restore access (though it can dodge a narrower “You’ve hit your Opus limit” message specifically).
- A spend-limit message from a self-hosted gateway — a different thing entirely; that’s an admin-configured cap on a Claude apps gateway, not the plan-level window.
- A context/auto-compact warning — not a usage limit at all. It just means the conversation is nearing its auto-compact threshold.
Once you hit an actual session or weekly limit, run /usage-credits (after /login with a claude.ai subscription — it’s not available on API key auth). For a Pro/Max subscriber it opens Settings → Usage on claude.ai, where you can turn usage credits on, check your balance and this month’s spend, and set a monthly spend limit. On Team/Enterprise, it either opens org usage settings directly (if you have billing access) or sends a request to an admin. Running it again while a request is pending won’t send a duplicate — it tells you one is already waiting.
For team admins: rate limits aren’t just a subscription thing
If your organization runs Claude Code through the Claude Console (API) rather than seat-based subscriptions, the constraint shifts from the 5-hour/weekly window to Token-Per-Minute and Request-Per-Minute limits set per workspace, and Anthropic publishes concrete starting recommendations by team size:
| Team size | TPM per user | RPM per user |
|---|---|---|
| 1–5 users | 200k–300k | 5–7 |
| 5–20 users | 100k–150k | 2.5–3.5 |
| 20–50 users | 50k–75k | 1.25–1.75 |
| 50–100 users | 25k–35k | 0.62–0.87 |
| 100–500 users | 15k–20k | 0.37–0.47 |
| 500+ users | 10k–15k | 0.25–0.35 |
Per-user allocation shrinks as headcount grows because concurrent usage rates drop in larger orgs — these limits apply at the org level, so individual developers can burst above their calculated share when others aren’t active. A 200-person org, for instance, lands around 4 million TPM total (200 × 20k).
Console-managed Claude Code traffic also runs through an auto-created “Claude Code” workspace that counts against your org’s overall API rate limits by default — worth capping separately with a workspace rate limit if you don’t want a heavy Claude Code day to crowd out production API traffic on the same account.
Usage limits vs. cost optimization vs. auto-compact
Three related but distinct things get conflated constantly:
| Usage limits | Cost optimization | Auto-compact | |
|---|---|---|---|
| What it is | The 5-hour/weekly wall on subscription plans | Reducing $-per-token spend, mainly relevant to API/Console billing | Claude Code summarizing old history to free context space |
| Who hits it | Pro/Max/Team/Enterprise subscribers | API and cloud-provider customers billed per token | Anyone, on any plan, in a long session |
| The fix | Wait for the window, add usage credits, or apply the tactics above | Model selection, prompt caching design, CLAUDE.md discipline — see our cost optimization guide | Not a problem to “fix” — it’s the mechanism working as intended, though you can steer it with /compact <instructions> |
They overlap in practice — the same discipline (small CLAUDE.md, clearing between tasks, right-sized models) reduces both token spend and how fast you burn through a usage window — but they’re not the same wall, and the fix for one doesn’t automatically fix the other.
Every setting referenced here — crossSessionInbound, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, hook definitions for output filtering — shows up in real projects’ settings.json files in our rules gallery, if you want to see how other teams have actually configured them.