Your usage limit gone before lunch

Two commands tell you everything. Run them, then match your symptom to the cause below.

Run these two checks

If your usage is under control and you just want headroom now, jump to the pay-as-you-go route. Everything between here and there is about making a plan last.

Set your strategy before you spend an afternoon optimizing. The right move depends entirely on whether you're hitting the session cap or the weekly cap.

The core reason people get surprised is that Claude Code enforces two independent limits, and the weekly one is invisible until it bites.

The 5-hour limit is a rolling session window that starts with your first message and resets five hours later. The weekly limit is a separate 7-day cap, and on Max plans there are two of them: one across all models and one for Sonnet only, per Anthropic's own usage docs.

These reset on different clocks. A heavy weekend can leave you session-capped on Monday with weekly headroom to spare, or weekly-capped with sessions to spare. Hitting a weekly cap locks usage until its 7-day reset even if your current five-hour session still has allowance. Waiting five hours does nothing.

One more thing that throws people: Anthropic stopped publishing fixed prompts-per-window and hours-per-week numbers. What it publishes now is relative capacity. Max 5x ($100/mo) gives 5x Pro's per-session usage, and Max 20x ($200/mo) gives 20x. So there's no public token figure to budget against. You have to read /usage and learn your own ceiling.

How the two caps interact

first message
     |
     v
5-hour session window starts
     |
     v
   session cap hit?  -- yes --> locked until session resets (5h)
     |
     no
     v
   weekly all-models cap hit?  -- yes --> locked until 7-day reset
     |                              (even with session headroom)
     no
     v
   sonnet-only weekly cap hit? (Max plans only)
     |
     yes --> sonnet locked; other models may continue
     |
     no --> keep working

If /usage shows your session low but you still hit a wall, it's the weekly cap. There's a known Claude Code issue where the session bar reads 2% while the limit fires at 32% weekly. The fix there is to trust the weekly number, not the session bar.

These are not HTTP error codes, they're the limit states Claude Code surfaces. Reading them correctly tells you whether to wait, switch models, or switch billing.

The trap is the fourth row. People see a fresh session bar, read "limit reached," and file a bug. In nearly every case it's the weekly cap, which the session bar doesn't show. Run /usage and read the weekly line before assuming anything is broken.

Each cause maps to a fix section below.

Most "my limit is broken" reports map to one of these rows. The weekly-cap-firing-at-low-session pattern accounts for a large share of the confusion, because the session bar and the weekly cap are different numbers and only one of them is visible by default.

Four core fixes handle most drains. The escalation path (pay-as-you-go + monitoring) covers the rest.

Fix 1: Default to Sonnet, reserve Opus for the hard parts

Switching your default model is the single biggest lever. Opus costs several times more per turn than Sonnet, and Sonnet more than Haiku. At API rates that's Opus 4.8 at $5/$25 per million input/output tokens, Sonnet 4.6 at $3/$15, and Haiku 4.5 at $1/$5. The real-world per-turn gap runs wider than the sticker ratio once Opus's heavier reasoning is counted.

Set Sonnet as your working default and pull Opus out only for the genuinely hard parts: architecture decisions, gnarly debugging, anything where a wrong answer costs you an hour. Use /model to switch. For most edits, refactors, and test writing, Sonnet's output is hard to tell apart and it stretches your weekly cap several times further.

Fix 2: Stop subagents from burning Opus in parallel

Subagent fan-out is the quietest drain because it doesn't show up while you're typing. Each subagent runs its own API requests in a fresh context window. It doesn't inherit your session, so it re-reads what it needs and bills its own calls. Agent teams can use about 7x the tokens of a standard session. One developer who blew through Max 20x found 85% of the usage came from subagent-heavy sessions.

The trap: most setups have every subagent inherit the main session's model, which is usually Opus. So every worker pays Opus prices on tasks that don't need Opus quality. Route each worker explicitly in its frontmatter:

---
name: test-writer
model: sonnet   # not the parent's Opus
---

Model routing alone cuts the subagent line item by roughly 30%. For mechanical work like renaming, repetitive edits, or doc lookups, drop those workers to Haiku.

Fix 3: Trim MCP servers before they eat your window

MCP servers charge you before you do anything. Seven connected MCP servers can consume 67,300 tokens of tool definitions, which is 33.7% of a 200k context window, at session start. Each tool's catalog runs 200 to 800 tokens of prose plus schema, multiplied across roughly 50 tools per server. That overhead rides along on every turn, so it compounds against your weekly cap fast.

If you run a handful of servers full-time, /context is the fastest audit you have. A common result is finding two or three servers you forgot you connected, each quietly costing you five figures of tokens per session.

Fix 4: Keep the cache warm with /compact and /clear discipline

Context hygiene protects your prompt cache, and a warm cache is most of your savings. Prompt caching cuts cached input cost dramatically. Cache hit rates of ~90% are healthy on the 5-minute default and climb to ~97-99% on the 1-hour TTL. The thing that kills it: adding or removing a tool mid-session invalidates the cached prefix and forces a full re-read. Lock your tools and model at session start.

Then manage the window deliberately:

The same drains apply on every plan, but the right lever shifts as you move up tiers.

There's no public outage history for plan limits because this isn't a service-down problem. It's a set of repeating behaviors.

The phantom-limit pattern accounts for a large share of confusion, because the session bar and the weekly cap are different numbers and only one of them is visible by default.

Nothing changed, but the scare was real and worth understanding.

Anthropic announced that Agent SDK and claude -p usage would move off your subscription into a separate, dollar-denominated monthly credit billed at standard API rates: $20 for Pro, $100 for Max 5x, $200 for Max 20x, with no rollover.

Then, before the June 15 effective date, Anthropic paused it. Those surfaces still draw from your Pro and Max subscription limits exactly as before. There's no credit to claim and your limits are unchanged. Anthropic says it's reworking the plan and will give advance notice before any future revision.

What this means for you: don't restructure your workflow around a credit pool that doesn't exist yet. The fixes above target the limits that are actually live today.

If /usage shows your weekly cap exhausted and you can't wait for the reset, the only real escape from a plan ceiling is metered billing.

Subscriptions are cheaper at daily-primary-tool volume. At that load the same tokens cost roughly 2 to 2.5x more at raw API rates than the $100 Max 5x flat fee. But subscriptions hard-stop you at the weekly cap, and pay-as-you-go has no weekly cap at all.

For bursty, headless, or unpredictable work, metered billing wins outright. An OpenAI-compatible gateway lets you point Claude Code (or any OpenAI-SDK client) at a single key, billed per token with no plan ceiling, and switch between Claude, GPT, and Gemini models without juggling provider accounts:

# point Claude Code at any OpenAI-compatible gateway of your choosing
export ANTHROPIC_BASE_URL="https://your-gateway.example/v1"
export ANTHROPIC_API_KEY="your-key"
# Claude Code now bills per token, no weekly cap

In code, the model string is the same shape you'd use anywhere — one key, swap to opus/gpt/gemini freely:

client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[{"role": "user", "content": "refactor this module"}],
)

The realistic ways forward, ordered by when each is the right call.

A plan limit isn't a bug to file. It's a budget you can read. Run /usage, default to Sonnet, and the wall you hit by lunch moves to the end of the week.

The point of all of this is to never be surprised again. Three commands give you everything you need.

Build the habit of a quick /usage and /context at session start. Two seconds of reading prevents the by-lunch lockout that brought you here.

The fixes above make a plan last. The lesson is that the limit that bites you is the one that isn't visible by default.

You can read this two ways. The narrow way: switch to Sonnet, trim MCP, route subagents, move on. The useful way: a tool whose real ceiling is a weekly number it doesn't surface by default will keep surprising you until you build the habit of reading it.

We see this in nearly every AI stack we audit. A team buys seats, hits an invisible weekly wall mid-sprint, and blames a billing bug — when the actual problem is that nobody read /usage and the model default was Opus. The Claude Code limit wall is a specific instance of a general problem: budgets that aren't observable aren't managed.

If your usage keeps surprising you, the limit isn't broken — your visibility into it is.