METHODOLOGY

Why you hit your Claude Code limit

AUGUST 25, 2026 · 8 MIN
TL;DR

At Anthropic's published API prices, rewriting a session after a cache miss costs far more than reading a large instruction file from the cache, so deal with cache misses before you trim the file.

  • A subscription limits you with a 5-hour window and a weekly window, and on Max the weekly window has a separate cap for Opus.
  • A cache miss, such as leaving a session idle past the cache timer, makes Claude Code write the whole session to the cache again.
  • Read the /usage screen before you change anything, because it is the only place that shows which cap you are actually hitting.

Twice in two weeks, I hit the weekly cap on Claude Max, Anthropic's $200-a-month plan that gives 20 times the usage of its Pro plan. I usually run several workspaces and agents at once in Claude Code (Anthropic's coding agent), and the cap doesn't wait for a convenient moment: it stops implementation in the middle of a large plan, right when I'm in the flow of things.

My first guess was that my CLAUDE.md (the instruction file the agent reads at the start of every session) was too big. I'd been piling instructions into it for months, so I opened it up to start cutting. This post covers what's worth knowing before you cut anything: how the subscription limits work, how prompt caching works, and the habits that follow from both, starting with the one screen to read before you change anything.

How a subscription limits your usage

On the pay-as-you-go API, each token has a price and you pay for what you use, which is the subject of the companion post. On a flat subscription such as Pro or Max, you pay a fixed monthly fee, and the constraint is a rate limit (a cap on how much you can use inside a time window). Two of them run at once, and both are shared across Claude chat and Claude Code:1

  • A 5-hour session window, the short one you bump into during a long working session.
  • A weekly window, the slower one that catches heavy users. It has a cap across all models plus a separate cap for Opus. Opus and Sonnet are two of Anthropic's current Claude models, and on Max they draw from separate buckets, while on Pro they share one pool.2

So on a subscription the goal is staying under the caps. Anthropic publishes per-token prices for the API but does not publish how heavily a subscription counts each kind of token, so I use the API prices in the next section as a guide to that weighting. All the prices, limits and mechanics in this post were recorded on August 25, 2026, so check the current documentation before you rely on a number.

The four kinds of token and what the input kinds cost

A model reads text as tokens (small units of text, each one counted and billed), and every token falls into one of four kinds, the way a letter and a parcel both go through the mail but don't cost the same to send. Fresh input is new text the model hasn't stored. A cache write stores a block of context so later turns can reuse it, and a cache read is one of those later turns reusing it. Output is what the model writes back, including its extended thinking (the reasoning it works through before it answers), which is billed as output; this post leaves output prices aside. The three input kinds are priced very differently relative to the base input price:3

cache read0.1×
fresh input1×
cache write · 5 min1.25×
cache write · 1 hr2×

Documented API prices, input side only. Output tokens are not shown.

Price per token for each input kind, relative to the base input price

How prompt caching works

On every turn, Claude Code sends the session's context to the model again along with your new message: the CLAUDE.md, the files it has read, and every earlier turn. Prompt caching is what keeps that affordable. Think of the cache as a whiteboard in the model's office. The first time a big block of context arrives, the model writes it on the board. Every later turn that starts with the same prefix (the unchanged beginning of the conversation) only has to read the board.3

One session's cache, from the first write to a rewrite after the timer runs out
  1. Turn 1 · WRITEcache-write price
  2. Turns 2…N · READcache-read price each
  3. Idle past timer · MISSboard erased
  4. Next turn · REWRITEwhole context written again
WHAT A BIG CLAUDE.MD COSTS PER TURNA common assumption is that a big CLAUDE.md costs full price on every turn, so trimming it saves a lot. At the API prices above, the file is read from the cache on every turn after the first, so cutting 2,000 tokens from it saves about 200 tokens' worth of fresh input per cached turn. Some community log analyses allege that a subscription weights cache reads more heavily than that. The larger cost sits on the turns where the cache has to be written, which the next section covers.

What causes a cache miss

A cache miss happens when the model looks for the board and finds it wiped, so the whole context is written to the cache again at the cache-write price, and the bigger the session, the more that rewrite costs. It happens in two common ways.

Leaving the session idle. The cache has a TTL (time to live, the timer after which the board is erased). In Claude Code the default is 1 hour on a subscription and 5 minutes on usage credits (pay-as-you-go top-ups) or an API key.4 Step away for longer than that, say for a lunch that runs past the hour, come back and type "ok, continue," and that one message rewrites the whole session. The Claude Code team has described the extreme case: a context of more than 900,000 tokens, left idle past the one-hour timer and written to cache all over again on the next message.5

Changing something near the start of the context. The board only counts as a match when the prefix is identical down to the byte, so any change invalidates the cache from that point on, and everything after it is written again.3

WHEN THE CACHE TIMER DROPS TO FIVE MINUTESTopping up a subscription with usage credits, or disabling telemetry (the usage data Claude Code sends back to Anthropic), drops a subscriber to the 5-minute timer without any warning, because the 1-hour timer depends on telemetry being on. Separately, around March 2026 the default regressed from 1 hour to 5 minutes, and one community log analysis reported a 20–32% rise in cache-creation cost as a result. Because these defaults have changed before, check which timer your own setup gets.

My ranking of what drains a subscription

Putting the mechanics together, this is how I'd rank what drains a subscription, highest impact first. The habits in the next section take them in roughly the same order.

cache misseshighest
oversized sessions
tool-result bloat
no /clear between tasks
Opus on trivial work
idle background sessions
heavy tool catalogs
bloated CLAUDE.md
over-budgeted thinking

Bar lengths show the order only.

What drains a subscription, highest first · the order is my own ranking and was not measured

Habits that keep you under the cap

Start with /usage, since it is the only view that shows which cap is actually binding, and it flags behaviors, such as cache misses and long context, that account for 10% or more of your usage. /cost is an alias for the same screen.6 Once you know which cap you are hitting, these are the habits I'd look at, in order:

  • Clear before a long break. If the break will outlast the cache timer, the cache will expire anyway, so write a short handover note and run /clear, the command that starts the session over with an empty context. You come back to an empty session instead of paying to rewrite a big one, and for a small session it hardly matters either way.
  • Start a new session for a new task. A finished task's context makes every later turn bigger, so run /clear between unrelated jobs instead of carrying the old one along.
  • Read less into the session. Tool-result bloat (file contents and command output that stay in the session and ride along on every later turn) is third on my list. Ask for a function or a line range instead of the whole file, and pipe long command output through grep or head (shell commands that filter or shorten it) before it lands in the chat. Don't scope so tightly that the model has to retry, though, since each retry adds another read on top of the first one.
  • Match the model to the cap you're hitting. On Max, Opus has its own weekly cap and Sonnet draws from a separate bucket, so if /usage shows the Opus cap is the one you keep reaching, moving routine work to Sonnet relieves it. Extended thinking is billed as output and counts toward output rate limits, so keep long thinking for work that needs it.
  • Close the sessions you aren't using. A community report on GitHub about idle and background sessions draining quota describes a Pro Max 5× quota exhausted in 1.5 hours.7 Keep one live session per thing you're actively doing.
  • Trim what loads into every session last. Anthropic suggests keeping CLAUDE.md under 200 lines,8 and /doctor, Claude Code's setup health check, tells you when the file has grown too big and flags unused MCP servers (plug-in servers that give the agent extra tools, whose tool definitions take up context before you type anything).6 One community report on GitHub describes cache re-reads of CLAUDE.md dominating a user's quota,9 so the file is still worth keeping to essentials.

The tool I built to see where my tokens go

Hitting the cap twice made me want better visibility into where my tokens were going, and recommendations I could act on, so I started building a tool for it. AgentWrangler is a local dashboard that reads Claude Code's own session logs, shows where the tokens went, and warns you before you reach a limit. It flags several of the patterns in this post: an oversized always-loaded context, a long session carrying its whole history, and an Opus turn that Sonnet could have handled. It runs on your machine and nothing it records leaves it, which is how I'd want my own telemetry handled anyway. AgentWrangler is now public on GitHub and npm, and the launch post covers it in full.

Footnotes

  1. Anthropic Help Center, "Use Claude Code with your Pro or Max plan" and "How do usage and length limits work?" (2026): a 5-hour and a weekly window, shared across Claude chat and Claude Code; only relative plan multipliers are published, not absolute token budgets. First-party. ↩

  2. Anthropic, Max plan and pricing pages: Max is 5× ($100/mo) and 20× ($200/mo) Pro; the weekly window has an all-models cap plus a separate Opus cap; on Max, Sonnet and Opus draw from independent buckets, shared on Pro. anthropic.com/news/max-plan; anthropic.com/pricing. First-party. ↩

  3. Anthropic, Prompt caching documentation: cache write 1.25× (5-minute) or 2× (1-hour) and cache read 0.1× of base input; exact-prefix matching, where any change invalidates the cache from that point. platform.claude.com/docs/en/docs/build-with-claude/prompt-caching. First-party. ↩ ↩2 ↩3

  4. Anthropic, "Claude Code: manage costs effectively" (code.claude.com/docs/en/costs) for the 1-hour-on-subscription and 5-minute-on-credits default and the telemetry gate; GitHub anthropics/claude-code issues #46829 and #84253, and the recca0120 log analysis, for the March 2026 default regression and the reported 20–32% cache-creation cost jump. First-party doc plus community reports. ↩

  5. Boris (Claude Code team), Hacker News item 47880089: a worked example of a 900,000-plus-token context, idle past the 1-hour TTL, written to cache again on the next message. First-party, forum comment. ↩

  6. Anthropic, Claude Code commands reference: /usage shows plan-usage bars and flags behaviors at 10% or more of usage; /cost is an alias for /usage; /doctor is a setup health check (installation, PATH, unused MCP servers, CLAUDE.md size). code.claude.com/docs/en/commands. First-party. ↩ ↩2

  7. GitHub anthropics/claude-code issue #45756 ("Pro Max 5× quota exhausted in 1.5 hours"): a community report of idle and background sessions draining quota. Community/practitioner. ↩

  8. Anthropic, "Claude Code: manage costs effectively": "Aim to keep CLAUDE.md under 200 lines by including only essentials." First-party. ↩

  9. GitHub anthropics/claude-code issue #24147: a community log reconciliation describing cache-read re-reads of CLAUDE.md dominating quota. Community/practitioner. ↩

Trust belongs in the schema, not the application.
The operating principle behind every project here. A rule the database enforces can't be forgotten in a hurry. Constraints, denied-by-default access, append-only logs — the controls that hold are the ones the system won't run without.