Why you hit your Claude Code limit

Twice in two weeks, I hit the weekly cap on Claude Max — the $200 "20×" plan — and got told to come back in a few days. I usually run several workspaces and agents at once, and the cap doesn't wait for a convenient moment: it stops implementation in the middle of a large plan, right when you're in the flow of things, which is exactly when it costs the most. I hadn't done anything wild. I hadn't written a novel. And the usage screen just showed a big bar that said I'd used my week.

My first guess was the same one almost everyone makes: my CLAUDE.md is too big. I'd been piling instructions into it for months — the file the agent reads at the start of every session. So I opened it up to start cutting. That instinct was wrong, and chasing it would have saved me almost nothing. The real drain doesn't show up as a big instruction file. It shows up as a cache miss, it's invisible on any per-token chart, and the fix is how you work, not how much you cut. This is the machinery, explained just deeply enough that the fix makes sense.

You're not spending dollars — you're spending headroom

There are two completely different meters, and confusing them is the root of most of the panic.

On the pay-as-you-go API, each token has a price; use more, pay more. Simple, and it's the subject of the companion post. But on a flat subscription — Pro, Max, Team — you don't pay per token at all. You pay a fixed fee and get a rolling allowance of compute. The real constraint is a rate limit (a cap on how much you can burn inside a time window), and there are two of them running at once, both shared across Claude chat and Claude Code:¹

• A 5-hour session window — the one you bump into mid-afternoon.
• A weekly window — the slower one that catches heavy users. It isn't one tank: there's a cap across all models, plus a separate cap just for Opus. On Max, Sonnet and Opus draw from independent buckets; hit the Opus cap and you drop to Sonnet, hit the all-models cap and everything stops.²

So if you're a subscriber, "saving money" is the wrong goal. The goal is staying under the caps. The token weights below are published as API prices; on a subscription, read them as how heavily each token counts against your allowance. Same ratios, different meter.

Four kinds of token, priced like postage

Here's the fact that changes everything: "tokens" is not one number. A model doesn't read words, it reads tokens — chunks of about 3–4 characters, roughly three-quarters of a word. And every token is billed in one of four categories, weighted very differently, the way a letter and a parcel both go through the mail but don't cost the same to send.³

The one to internalize: cache read is the cheap glance; cache write is the expensive event. Whenever someone says "that was 50,000 tokens," ask which kind — 50,000 cache reads cost about as much as 5,000 fresh ones.

The whiteboard: how caching works

Every turn, Claude Code re-sends the whole conversation — the API has no memory between requests, so your CLAUDE.md, the files you loaded, and every earlier turn go up the wire again each time. If that were re-processed from scratch on every turn, long sessions would be ruinous. They aren't, because of prompt caching.

Think of the cache as a whiteboard in the model's office. The first time you send a big block of context, the model writes it on the board — the expensive part, a cache write at 1.25× or 2×. Every later turn that starts with the exact same prefix just glances at the board: a cache read at 0.1×. It works on the prefix — the unchanged beginning of the conversation — and matches on the exact bytes.³

When the whiteboard gets erased

A cache miss is when the model reaches for the whiteboard and finds it wiped. The entire prefix has to be written again at full cache-write price — not just the part that changed, all of it. This is the real quota killer, and it happens four common ways.

1. The idle trap. The cache has a timer — a TTL ("time to live"). Every read resets the clock; pause longer than the timer and the board is erased. Come back from a coffee break, type "ok, continue," and that one innocent message rewrites the whole session at full price. The bigger the session, the bigger the bill for the coffee. The Claude Code team has described the extreme version: a context near a million tokens, idled past the timer, re-written to cache all at once on the next message.⁴

2. Editing context mid-session. The cache matches on the exact prefix. Edit CLAUDE.md, toggle a plugin, change a tool definition — any change, even a single space, invalidates everything after it.³

3. Switching models or reopening old sessions. Caches are per model. Switch from Opus to Sonnet mid-session and the new model starts with an empty board; reopen a big session from yesterday and you pay one full rewrite before you get any work done.

4. The backfire trap. This one is almost funny. You read that big instruction files waste tokens, so mid-session you trim CLAUDE.md to save some. That edit invalidates the cache, which triggers a full-price rewrite of the entire session — you've just spent far more than the trim will ever save back. The "optimization" is the spike.

Where the quota actually goes

Put it together and the ranking of what drains a subscription looks nothing like the folk wisdom. Highest impact first — the top three amplify each other:⁵

Two of these deserve a word. Tool-result bloat is the quiet one: read a whole file, dump a verbose command's output, paste a long log, and every one of those rides along in the context on every future turn — like stuffing every receipt into your backpack and then carrying the backpack everywhere. Practitioners name it the single biggest silent drain.⁵ And idle background sessions — a session left open in another terminal keeps making calls (compaction, background agents), and every one draws from the same allowance; one community reconciliation traced most of a blown quota to sessions someone forgot were running.⁶

The playbook

None of these ask you to do less work. They change when you do things and how much rides along. A few are always-on; the rest involve a trade-off worth a thirty-second check.

• Clear before a long break. If your break outlasts the cache timer, there's nothing to preserve — only something to pay for on return. Write a short handover note, then /clear. The return message writes a few hundred tokens instead of rewriting the whole session. (Decide first: worth it when the session is big and the break is long; a tiny session is cheap to rewrite either way.)
• New task, new session. A finished task's context is dead weight that makes every later turn bigger and every miss more expensive. /clear between unrelated jobs; /compact at a phase boundary (exploring → building → testing), not on a timer.
• Load context once, up front — then read less. Front-loading is good; the waste is re-pasting a file or letting the tool re-read what it already has. Ask for a function or a line range, not the whole file, and pipe long command output through grep/head before it lands in the chat. (Always — the only risk is scoping so tight the model has to retry, which costs more than one honest read.)
• Close the sessions you aren't using. One live session per thing you're actively doing; everything else closed, not minimized.
• Plan with Opus, build with Sonnet — but check the tank first. Opus weighs more against your allowance. Plan with it, hand the plan to Sonnet, and switch at a /clear (switching mid-session empties the cache). Only if /usage shows the Opus or all-models cap is the tight one — if it's the Sonnet weekly bar, moving work to Sonnet makes it worse.²
• Trim CLAUDE.md, but only at a boundary. Anthropic suggests keeping it under ~200 lines.⁷ It's the smallest lever here, and the edit itself costs one rewrite — so do it right after a /clear, never mid-session.

And the one that isn't optional:

• Read /usage before you change anything. It's the only view of which cap is actually binding, and it flags the behaviors — "cache misses," "long context" — eating ≥10% of your usage. /cost is just an alias for it. /doctor is a different tool — a setup health check that will, among other things, tell you if your CLAUDE.md has gotten too big and flag unused MCP servers you're paying to load.⁸ Each diagnosis has a different fix, and trimming the prompt is the right first move in none of them.

The reframe

The lesson isn't "trim your context." It's that a cache miss is the expensive event — and you can't manage a cost you can't see. Everything above is either avoiding the miss or getting the evidence to know which miss you're paying for. The instinct to cut the biggest file is exactly backwards: the biggest file, cached, is nearly free; the small habit that erases the cache is what costs you the week.

That's the gap I kept falling into, and reading /usage after the fact was never enough — it tells you the tank is empty, not which habit drained it. So I started building the thing I actually wanted: a local dashboard that reads Claude Code's own session logs off your machine, shows where the tokens went, and warns before you hit the wall instead of after. It stores only the counts — token totals, sizes, model, timing — and throws the message content away; nothing leaves your laptop, which is the least-privilege posture I'd want for my own telemetry anyway. It flags the exact patterns in this post: the oversized always-loaded context, the marathon session carrying its whole history, the Opus turn a cheaper model would have served.

It's called AgentWrangler. The code's still local, but an early PRD is up at github.com/Doogit/AgentWrangler if you want to follow where it's headed. Stay tuned.