Skip to content

How to Stop Hitting Claude Code Usage Limits

The complete guide to Claude Code usage limits: context hygiene, model routing, cache hits, hook enforcement, subagents, and offloading I/O to cheaper models.

Tuan Tran Van
35 min read
Updated 24/10/2026
Contents (18 sections)
  1. What the quota counts, and why a full context window is not a usage limit
  2. Why your usage drops fast even when you type very little
  3. Keep the session light: clear at the right time, point at the right files
  4. Write prompts you do not have to pay for twice
  5. Match the model and effort level to the job
  6. Earn cache hits instead of paying full price every turn
  7. Cut the fixed cost you pay on every turn
  8. Move heavy work out of your main session
  9. Should you replace file reading with a code graph?
  10. Enforce it instead of asking nicely
  11. Send the I/O to a cheaper model
  12. Four layers of output compression
  13. Find the real leak with /usage and /context
  14. Schedule your work around the five-hour window
  15. What to do when you have already hit the limit
  16. If you also use Claude on the web
  17. Which three habits should you start with?
  18. References

Claude Code usage limits run on two independent counters: a five-hour rolling window that governs bursts, and a weekly cap measured in active compute hours

and hitting either one throttles your access until that specific window resets.

This pool is not isolated to the CLI. It is a shared bucket across Claude Code, the Claude.ai web interface, and Cowork, so a heavy morning of web chat directly shrinks what your terminal has left in the afternoon. Optimizing is not about typing less.

It is about not paying for context Claude never needed in the first place.

Two parallel counters governing Claude Code usage limits: a five-hour rolling window covering bursts of work and a weekly cap measured in active compute hours

What the quota counts, and why a full context window is not a usage limit

You have to separate two things that fail in completely different ways. The context window is how much text the model can hold in a single conversation, up to 1M on some paid plans. The usage quota is the metered allowance for total work performed over time. You can have plenty of context space left and still be locked out, because the quota tracks cumulative compute across every session you run.

The two counters work differently. The five-hour rolling window limits prompts based on context length and model choice, resetting five hours after your first prompt in a session. The weekly cap is measured in active compute hours, meaning time when the model is genuinely processing tokens or reasoning. Time you spend reading output or browsing files does not count against it.

Context window versus usage quota: the context window is per-session memory that auto-compacts when it fills, while the usage quota is a budget over time that blocks you until it resets

This is where most people get confused, and Anthropic's documentation states it plainly: a context or auto-compact warning is not a usage limit. When your context window fills, Claude Code summarizes older history to free space and you keep working. When your quota runs out, you stop until the window resets. Different problem, different fix.

One caveat before you trust any number you read online. Anthropic does not publish exact token quotas. It publishes multipliers: Pro at 1x, Max at 5x and 20x. Every "45 prompts per five-hour window" figure in circulation is a community estimate, not a specification, and it shifts with your context length and model choice.

One more piece of old advice is worth retiring: "work off-peak" is no longer the fix. In May 2026 Anthropic doubled the five-hour limits across paid Claude Code plans and removed the peak-hours reduction entirely for Pro and Max. Any guide still telling you to code at midnight to stretch your quota is out of date. Hitting the wall today is almost always a workflow problem, not a scheduling one.

Why your usage drops fast even when you type very little

The primary driver is context accumulation. Every message you send resends the entire conversation history, every file currently loaded, and all tool definitions. The 50th turn in a session is dramatically more expensive than the first, which is why a one-line question late in a long debugging session still draws heavily on your quota. softens this — repeated content bills at the cheaper cache-read rate — but the volume is still traveling with every request.

Context accumulation across turns: the first turn sends only a question, while by turn 50 every new message still carries the entire conversation history behind it

The mental model that helps most: the scoreboard is context weight, not message count, meaning the mass of old history, files, memory, and tool definitions Claude has to carry into the next turn. Dump a log file into turn one of a thirty-turn session and you do not pay for it once. You pay for it thirty times.

A few things consume disproportionately. Agent teams use roughly 7x the tokens of a standard session when teammates run in plan mode, because each teammate maintains its own and runs as a separate instance. Pasting file contents directly into the terminal is far more expensive than referencing a path, because whatever you paste sits in context in full for the rest of the session. And leaving Opus as your default burns premium compute on work Sonnet handles at a fraction of the cost.

There is also a quiet baseline. Background conversation summarization for the resume feature and status-checking commands consume a small amount even when you are idle, typically under $0.04 per session. Individually trivial; worth knowing about when you are auditing where your week went.

Keep the session light: clear at the right time, point at the right files

Proactive context management is the single most effective lever you have, and the cheapest to adopt.

Three session-hygiene habits: /clear to stop carrying old work, /compact to condense history and continue, and pointing at an exact file path instead of pasting the whole file

Use /clear whenever you switch to unrelated work. A useful test: if your next prompt would make perfect sense typed into a brand-new terminal, clear before sending it. Your CLAUDE.md and project files stay available, and only the chat history goes. One warning: /clear cannot be undone, so copy anything you still need out of the history first.

The boundaries get obvious once you think in units of work: research done, writing starts; plan done, implementation starts; one bug fixed, next bug begins; draft done, review starts. Not every five minutes, but every time a unit of work closes.

One point that is widely misunderstood: /clear does not refund usage you have already spent. It does not reset the rolling window either. All it does is stop future turns from carrying stale history. Clearing early saves a lot; clearing after you hit the wall saves nothing.

Use /compact when you are mid-task and need to continue. Do not run it blank. Tell it what to preserve (/compact Focus on code samples and API usage) because a default summarization can flatten decisions, file paths, and next steps you still depend on. /clear stops you carrying the old thing; /compact lets you keep going.

If you want a reusable version, name what survives and what does not:

text
/compact Preserve only:
1. Current goal and success criteria
2. Decisions already made
3. Files read or changed, with paths
4. Source URLs or citations that must survive
5. Commands and tests already run, with results
6. Open risks and TODOs
7. The exact next action
 
Drop:
- discarded approaches
- repeated explanations
- old drafts
- verbose logs
- background already covered in project files

Consider /compact once a session passes roughly 30 turns, and never compact in the middle of an uncommitted multi-file edit, because afterwards the model can lose track of which files it already modified. If you want the system to handle this earlier on its own, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 moves auto-compact to 50% of the window instead of waiting until it is nearly full.

Reference files by path rather than pasting them. The @ prefix injects the entire file plus its CLAUDE.md tree into context, so when your goal is saving tokens, use a bare path and name the part you care about, as in "look at the validateToken function in src/auth.ts". For logs and stack traces, trim to the relevant 20 or 30 lines before pasting anything at all.

End every phase with a handoff artifact. This is what makes /clear safe: a research brief, a plan file, an audit report, a short note. Useful contents are goal, what is done, files changed, files read, commands run, decisions, risks, next action, and what not to repeat. A quick test: if a task cannot survive a cleared chat, it is leaning too hard on conversation memory.

Resume long sessions from a summary. The subscription cache lives for one hour. If you step away for longer and reopen a large session, the next turn reloads the whole context at uncached rates. Pick the summary when resuming and you skip that bill.

Write prompts you do not have to pay for twice

Most quota goes on the correction chain that follows a hard question. The question itself is rarely the expensive part.

Stop sending correction chains. The "do this" → "no, I meant…" → "also add…" pattern forces Claude to carry the original bad prompt, the wrong output, your correction, the second wrong output, and the next correction. Rewriting the request cleanly and sending it once is far cheaper. A structured brief (audience, goal, tone, must-include, avoid, output format) looks longer but removes the ambiguity that generates the chain in the first place.

Batch related requests into one turn. "Rename the userId variable and extract the validation logic into a helper" pays the transcript tax once instead of twice, and the answers are often better because the model sees the whole picture. Batching has rules, though: only batch work that shares context. Never batch unrelated projects, tasks that want different models, or "read the whole repo and tell me" when you need one function.

Draw instead of describing. For architecture, a six-line Mermaid diagram carries the same shape as three paragraphs, and Claude parses it natively.

One accurate pass beats five cheap ones. This is the necessary counterweight to every downgrade-the-model tip below: saving tokens by picking a model that is under-powered for the job just moves the cost into rework. A principles file in the Karpathy style (think before coding, prefer the simple option, make surgical changes, work to an explicit goal) saves indirectly but heavily, because it removes clarification loops and rewrites.

Match the model and effort level to the job

Sonnet is the right default for most coding work: features, tests, known bugs, ordinary refactors. Reserve Opus for the cases that actually need deeper reasoning: hard debugging, cross-cutting refactors, architectural decisions. Haiku handles mechanical work like renames, boilerplate, and regex explanations at the lowest cost. For a more systematic take, see how to choose the right AI model.

Matching model tier to task difficulty: Haiku for mechanical work, Sonnet for everyday coding, and Opus reserved for planning and wide-reaching changes

On published API rates, Opus costs roughly 1.7x Sonnet per token and Sonnet roughly 3x Haiku, so Opus runs about 5x Haiku for identical work. Fix a one-line CSS bug with Opus and you have spent the budget for five of those fixes on Haiku.

The highest-value pattern is plan with Opus, execute with Sonnet. A plan costs a few hundred tokens; a wrong 400-line diff that you revert and regenerate costs thousands, twice, plus the turns spent explaining what went wrong. The /model opusplan setting does this for you — Opus while planning, Sonnet for execution — and switching models mid-session does not clear your conversation, so Sonnet still sees everything Opus produced.

The pattern only pays when the plan is thick enough that the cheap model never has to guess. Do not let Opus write the plan in one pass: make it interrogate you until the things neither of you knew are on the table, then lock the design, components, interfaces, and data flow. Every time you plan a feature, also have it output an architecture decision record (ADR) and an update to the project glossary, and commit both. Those two files answer "why did we do it this way" and "what does this term mean" for every later session at a cost of a few hundred tokens, instead of Claude re-reading code to infer them. Matt Pocock's skills ship exactly this workflow (CONTEXT.md as the glossary, ADRs as the decision log).

The commonly missed piece is subagents: they draw on the same quota, and they do not default to a cheap tier. CLAUDE_CODE_SUBAGENT_MODEL pins every delegated agent to a cheaper model globally, instead of editing each agent file by hand. Research, audits, and codebase scans rarely need your strongest model.

Model availability differs by plan. Pro and Team Standard users need usage credits to reach Fable 5; Max and Team Premium include it but cap it at around 50% of the weekly limit.

Finally, tune effort. Extended thinking is billed as output tokens, and the default budget can run to tens of thousands of tokens per request. For simpler tasks, lower the level with /effort or disable thinking in /config. On models with a fixed thinking budget you can set MAX_THINKING_TOKENS=8000 directly, but adaptive-reasoning models ignore that variable, so there, /effort is the real control.

Earn cache hits instead of paying full price every turn

Prompt caching bills the matching leading portion of a request at a much lower rate. You control whether you hit that cache, through the order you assemble content in.

The rule is to keep the prefix stable and put the varying part last: bulk files, documentation, and long background first, the specific question at the end. Ask three questions about the same file set and the first pays full price while the next two pay a fraction for the cached prefix. Do it the other way around, with the question or a timestamp at the top, and you invalidate the cache on every single turn without noticing.

The same logic makes anything that churns the head of your request expensive: toggling servers mid-session, editing CLAUDE.md constantly, injecting dynamic content at the top of prompts. Some commercial compression proxies ship a component whose entire job is stabilizing the prefix so the cache actually hits, which is good evidence this is a real leak rather than a rounding error.

Cut the fixed cost you pay on every turn

Some of your budget is spent before you type anything: the , tool definitions, and everything loaded automatically at session start. This is the most valuable category to trim, because it multiplies across every single turn.

The fixed cost paid on every turn: CLAUDE.md is always loaded, Skills load only when invoked, and enabled MCP servers occupy context permanently

Keep CLAUDE.md lean. It is prepended to every turn, so every line you never needed is a permanent tax. Aim to stay under roughly 200 lines. A good rule for what earns a place: only add a note the second time you have to correct Claude on the same thing, since first-time issues are usually one-offs. Re-read the whole file every few weeks and delete whatever is no longer true, because a stale note is worse than a missing one, because it actively misleads.

Once the file has grown, the fix is not tighter wording but turning it into a table of contents (progressive disclosure): a short core that always loads, with pointers to deeper docs Claude opens only when the task calls for them. According to Paul Iusztin (Decoding AI, 2026), OpenAI keeps the AGENTS.md for a roughly million-line, Codex-written codebase at about 100 lines, acting as a map into a docs tree that a linter checks. There is a trap here: an @ import does not make the file cheaper, because the Claude Code docs state that imported files load together with the CLAUDE.md that imports them, so imports organize rather than save tokens. Real tiering needs things that load on demand: a CLAUDE.md inside a subdirectory, rule files with a paths field (loaded only when Claude works with matching files), or a bare path in backticks that Claude opens with its file-reading tool when needed.

A variant worth adopting is per-stack rule files: .claude/rules/react.md, .claude/rules/flutter.md, each opening with a single "invoke this skill first" line, then listing the handful of mistakes Claude actually repeats in your codebase. That list has to come from failures you have seen rather than from a tutorial, which is exactly why it stays short and pays for itself.

Move specialized instructions into skills. Workflows like PR review standards or database migrations do not need to sit in context permanently; skills load on demand only when invoked, which keeps your baseline small.

But skills are not free: every skill's description sits in context for the whole session whether you use it or not, because that description is what Claude reads to decide whether to load the skill. The spec caps descriptions at 1024 characters, the /skills listing truncates display at 250, and the whole allowance runs at roughly 2% of your context window (tunable via SLASH_COMMAND_TOOL_CHAR_BUDGET). Practical conclusion: write tight descriptions using the verbs you actually type ("writing", "reviewing", "running tests"), and do not keep twenty skills when you use three.

The cleanest decision rule for what deserves a skill at all: cache anything you have explained twice. Test conventions, deploy flow, logging patterns, code style: re-explaining each of those every Monday is paying for the same paragraph every week.

Reduce MCP (Model Context Protocol) overhead. Claude Code's tool search is now on by default, so at session start it loads only tool names and each server's instructions, and a tool's full definition enters context only when Claude searches for it. That makes MCP far cheaper than it used to be, but not free, because every server still contributes its names and instructions, and setting ENABLE_TOOL_SEARCH=false drags every definition back into upfront loading. Run /mcp to see what is configured and disable anything you are not using. Where a CLI already exists (gh, aws, gcloud) using it directly is more context-efficient, because a CLI adds nothing to context at all. The better preventive habit is scoping: install an MCP server at project or local scope when it serves one repo, and reserve user scope for tools you want everywhere. Your MCP list should be deliberately boring.

Remove the built-in tools you never use. The heaviest part of the baseline is usually not CLAUDE.md but the built-in tool definitions. Iusztin published the numbers from a trimmed personal setup, on a 1M-token window: 21,400 standing tokens in total, of which 4,300 were the system prompt, 11,600 the system tools, 2,700 for 17 skills, and close to zero for 46 MCP tools thanks to tool search. Claude Code gives you official scissors: a deny rule naming a bare tool (no parentheses) removes that tool from context entirely, so Claude never sees it. If you never need Claude editing notebooks or searching the web on its own, declare it in settings.json:

json
{
  "permissions": {
    "deny": ["NotebookEdit", "WebSearch"]
  }
}

Two things to watch: set this before the session starts rather than mid-way, because changing the tool list changes the head of the request and breaks the cache; and if your CLAUDE.md already carries its own commit and PR conventions, includeGitInstructions: false drops the built-in git guidance from the system prompt so the two rule sets do not step on each other. At the far end are minimal harnesses (the control layer wrapped around the model) such as Pi, which start nearly empty and add features through plugins, for people who want to decide every line of the baseline themselves. Whichever route you take, open /context before and after you trim so you see the real number.

Consider turning auto memory off. Auto memory is the notes Claude writes for itself into MEMORY.md, and the first 200 lines (or first 25KB) of that file load into every session. You did not write it and rarely read it, but you pay for it on every turn. Turn it off with the toggle in /memory (saved as autoMemoryEnabled: false) or with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Only do this once continuity between sessions lives in files you control and have committed, meaning CLAUDE.md, handoff files, ADRs, and the glossary. Our piece on why you should delete Claude's auto memory goes deeper.

Move heavy work out of your main session

Verbose operations (running tests, reading large log files, fetching documentation) belong in a subagent. The noisy output stays in the 's own context and only a summary returns to your main conversation, which stops a single test run from inflating the cost of every turn that follows it. For simple scanning tasks, configure the subagent to run Haiku.

A subagent can burn tens of thousands of tokens reading, yet hand back only around 1,000–2,000 tokens of summary to the main session. Iusztin used exactly this to cluster the entire Decoding AI archive: Haiku and Sonnet subagents did the reading, Opus received only the summaries, and the main session's context barely moved.

Moving heavy work into a subagent: verbose output from test runs and log reads stays inside the subagent's context while only a short summary returns to the main session

The test for what to delegate: anything that produces artifacts you will never read twice. Codebase scans for call sites, dependency audits, digging through an 800-line file to find where authentication happens: all of it. And know what not to delegate: the file you are actively editing. Hand that to a subagent and your next prompts break, because the main thread no longer knows what you just changed.

A well-written subagent caps its own output, in its own system prompt:

markdown
---
name: codebase-scan
description: Find every call site of a function or pattern across the repo. Use when asked where something is called, defined, or imported.
model: haiku
---
 
Scan the codebase for the requested pattern.
Return: total match count, the top 3 directories, one example per directory.
Never quote more than 20 lines of code.

Both details in that file are savings. The description line is the trigger, because subagents are not invoked by slash command; Claude reads the descriptions and routes work itself, so use the verbs you actually type. And "never quote more than 20 lines" is what stops the subagent from handing the bloat straight back to your main thread, which would erase the entire benefit.

A second layer is preprocessing with hooks. Rather than letting Claude read a 10,000-line log to find errors, a PreToolUse hook can filter it first and return only the matching lines, cutting a request from tens of thousands of tokens to a few hundred. Configure it in settings.json:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }]
      }
    ]
  }
}

And the script it calls, which trims test output down to failures only:

bash
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
 
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
  echo "{}"
fi

Should you replace file reading with a code graph?

Yes, but only in some codebases, and this is where practitioners split into two camps. Questions like "where is this function called", "what does this architecture look like", "where does auth happen" are the most expensive kind to answer by reading files, because Claude has to open dozens of them to produce three lines of conclusion. The cheaper route is indexing the codebase into a queryable graph (tree-sitter AST parsing, stored locally) and asking the graph instead.

The same five structural questions cost around 3,400 tokens through a graph versus roughly 412,000 tokens exploring file by file. Our guides on cutting Claude Code tokens by 90% with a code graph and on Graphify cover the setup.

Two conditions make it actually pay. First, index once and reuse it, running change detection only after meaningful edits, since re-indexing per question just moves the cost somewhere else. Second, use the graph to locate, then read only the files it points at. A graph answers "where" very cheaply; "how do I change it" still needs Claude reading real code.

The other camp objects outright, and its argument deserves a hearing. A code graph is a second copy of the codebase, and every copy drifts from the original. Every refactor means another re-index; forget one and the graph points to the wrong place with full confidence, which is worse than having no graph. Iusztin cites the design of Claude Code and Codex as evidence, since both search at runtime with glob and grep instead of maintaining an index, so results always match the current code and there is nothing to keep in sync.

In this view, the code's own structure is the graph an agent needs: modules with clear boundaries, narrow interfaces, and one-directional data flow. When each module stands on its own (the test: could you lift it into another project and have it work?), a short table of contents in CLAUDE.md plus a few grep calls is enough for Claude to find the right place. Do not confuse a code graph with a glossary or an ADR either: those record concepts and decisions, not code, so changing the code does not force you to update them.

Code graphRuntime grep + clean modules
Upfront costIndex the repo, then re-index after big changesClose to zero
FreshnessDrifts until the next re-indexAlways matches current code
Strongest whenLarge, unfamiliar, legacy repo; cross-module questionsA repo you wrote, with clear module boundaries
RiskStale results mislead with confidenceMany reads if the structure is messy

In practice, if you are reading a large codebase you did not write, and reading more than changing it, the graph is worth installing. For my own repos, I would put the effort into clean module boundaries first, because that pays back longer than an index you have to keep feeding.

Enforce it instead of asking nicely

The strongest idea here is also the easiest to skip: Claude takes the path of least resistance every time, so one hook that blocks a wasteful pattern beats a thousand words in CLAUDE.md. Write "use the code graph before reading files" into your instructions and Claude complies for a few turns, then drifts back. A block does not drift.

Several hook patterns are worth building:

  • A discovery gate. A PreToolUse hook matching Read|Grep|Glob blocks the first such call of the session with a nudge to query the code graph; a PostToolUse hook touches a flag file in /tmp, scoped to the parent process ID, the moment the graph tool runs. Seeing that flag, the gate stands aside for the rest of the session. Blocking once is enough to change the behavior without jamming your day.
  • Ban raw inspection commands in Bash. cat, head, tail, grep, rg, find, and wc run through Bash land directly in context, bypassing every compression layer you built. A PreToolUse Bash hook should block them and force the throttled tools, including | head and | tail pipes, since the output still floods context before it gets trimmed. Always ship an escape hatch (an unlock file in /tmp that expires after ten minutes) for when you genuinely need the raw thing.
  • Re-inject the rules after every cleanup. A SessionStart hook matching startup|resume|clear|compact puts the protocol back into the session, so /clear does not wipe your discipline along with the history.
  • Reject scanners after every edit. A PostToolUse hook on Edit|Write runs your linter or a conventions script, and any violation goes straight back to Claude to fix before it moves on. That kills the most expensive loop there is: commit, red CI, re-explain, re-fix.

Send the I/O to a cheaper model

Most of what Claude does for you is I/O, not thinking. Reading five files to answer one question, generating a test file that is 80% boilerplate, rewriting documentation after a working session. Expensive work that barely touches the reasoning you are paying premium rates for.

The mechanism is simple: Claude Code's Bash tool runs anything on your PATH. So a ~60-line script calling any cheap OpenAI-compatible model with a large context window is enough to turn "read 5 files, burn 8,000 tokens" into "read a 400-token summary". No MCP server, no plugin, no marketplace.

Two tools usually cover it: one that takes a list of paths plus a question and returns a summary, and one that takes a spec plus a reference file and writes the generated file straight to disk for Claude to review. The routing rules in CLAUDE.md decide whether this works, not the script, and above all the "when not to delegate" half:

markdown
## Delegation to the worker model
 
Delegate: reading multiple files to answer one question, generating repetitive
tests, config, or documentation.
 
Do NOT delegate:
 
- tasks under ~2,000 tokens (the overhead is not worth it)
- architectural decisions, debugging, safety-critical code
- anything that needs careful reasoning
- anything where exact line numbers are required for editing

Without that second half Claude routes everything out, including the work you actually want it doing. State the boundary plainly: Claude thinks, the cheap model fetches and carries. One engineer tried delegating debugging and got back surface-level findings while the real bug — a race condition — went unnoticed until the strong model looked at it.

The biggest single win is usually documentation. Extract the human-readable conversation from the session's JSONL transcript, hand it to the cheap model along with the existing docs, ask for exact edits, and let Claude apply them. A documentation update drops from roughly 5,000 tokens to around 200.

Two traps to know up front. First, if the worker model has a thinking mode, set max_tokens high enough to cover reasoning and the answer, or otherwise it spends the budget on hidden reasoning and returns an empty response with no error at all. Second, cross-model review should come from a different vendor: switching families catches blind spots a same-family reviewer misses, and it costs nothing from your Claude budget.

Four layers of output compression

Beyond the filtering hook above, the community has built compression at four distinct points in the pipeline. They do not overlap, and you do not need all four.

  1. Sandbox the tool output. Instead of letting output flow straight into the conversation, this layer runs the command in an isolated subprocess, indexes the full output into a local searchable store, and returns only a compact summary, and the full text stays retrievable on demand. It is also where the batching trick lives: one batch-execute call replacing thirty individual tool calls. The same family covers "fetch and index" for URLs, pulling a page down and returning a few-KB preview instead of the whole document.
  2. Compress shell output in place. A small binary intercepts CLI output, strips boilerplate, groups repeats, and truncates intelligently, a good fit for git status, npm install, and short test results. RTK is the clearest example of this layer.
  3. Compress at the API layer. A proxy sits between Claude Code and the API and compresses the entire outbound payload: conversation history, system prompt, tool definitions, and even CLAUDE.md. It is the only layer that reaches what we have been calling fixed cost. There is a stranger variant too, rendering bulky blocks into dense text PNGs and letting the model read them visually, since vision tokens bill by image size. The trade-off is that vision is unreliable for strings that must be exact, so hashes, IDs, and secrets belong in recent text turns.
  4. Compress what Claude itself says. The argument here is simple: Claude's output becomes the next turn's input, so its verbosity compounds. A terse output style drops the hedging and pleasantries while leaving code and error messages untouched; the Caveman plugin is the most popular take on it. Apply the same compression to CLAUDE.md itself and the saving multiplies across every future session.

Two warnings have to travel with all of this. First, the startup cost is real: every MCP server, plugin, and hook loads definitions into every session. For a single one-off question, a heavily instrumented machine can cost more than stock Claude Code; the savings only appear once the workload is large enough to amortize that fixed cost. If /context shows your baseline jumping, trim before you add. Second, these tools see everything: compression proxies, MCP servers, and hooks can all read your prompts, code, logs, and session data; permission-reducing modes also remove human checkpoints; and project memory files must be gitignored, because they collect secrets easily. Do not paste-install the whole stack onto a machine with sensitive data.

Find the real leak with /usage and /context

These commands do not save tokens by themselves. They show you where the leak is, and it is usually not where you assumed.

Output of the /usage command in Claude Code: session and weekly usage bars alongside the behaviours consuming the most quota, including context over 150k, multiple parallel sessions and heavy skills

/usage breaks down recent consumption by skill, subagent, plugin, and individual MCP server, each as a percentage of the total. Press d for the last 24 hours or w for the last 7 days. When any single behavior accounts for 10% or more — long context, cache misses — Claude Code raises a behavior flag for it. These figures are computed from local session history on that machine, so usage from other devices or from claude.ai is not included. For authoritative cross-device numbers, check the Usage page under Settings on claude.ai.

/context inspects the current session instead: messages, files, tools, skills, memory files, and remaining space. It is the fastest way to spot irrelevant files sitting in context that you forgot were there.

If you want to be rigorous, measure before and after every change. There are CLIs that parse Claude Code's local session logs into daily, weekly, and per-session reports broken down by model, cache, project, and five-hour block, plus dashboards that compare cost across several AI tools. Without numbers you are trusting a feeling, and the feeling is usually wrong about which habit is expensive. A status line showing live context percentage alongside five-hour and seven-day usage is worth the setup too, because it shows the wall approaching without you running anything.

The culprit is often something structural rather than something you did. One practitioner discovered an automated WordPress workflow was consuming a large share of their weekly usage, invisible until they opened /usage and read the attribution.

Four self-audit questions, answerable in thirty seconds, will usually locate your leak:

  1. What was the default model in your last session? If it was Opus, your routing is leaking.
  2. How many raw file reads or greps landed directly in the main thread? More than two means delegation is broken.
  3. Did you re-type context a skill should have remembered? That is a caching failure.
  4. Is your current conversation older than your current task? That is a hygiene failure.

If you can only fix one, I would fix routing first, because it costs one slash command at the start of the day and shows a visible recovery the same afternoon. If several are broken, delegation moves the most budget per unit of effort.

Schedule your work around the five-hour window

The rolling window has a consequence worth exploiting: what you spent at 9am falls out of the window by about 2pm. Burning everything in one morning leaves the rest of the day's capacity on the table. Split the day into two or three spaced sessions and each one starts with a partially replenished allowance.

Pair that with a stopping rule: once you are around 80–90% through the useful window, stop opening new work. Spend what is left verifying what you just built and writing a handoff so you have a clean pickup point. Getting cut off mid-way through an uncommitted multi-file change costs far more than stopping ten minutes early.

What to do when you have already hit the limit

First, work out which ceiling you hit. The error message states when the window resets. A session limit clears within five hours; a weekly limit waits for your account's fixed reset day.

Switching models will not rescue you. The session and weekly windows are shared across all models, so /model does not restore access. The one exception is a model-specific message, and if you have exhausted Opus specifically, moving to Sonnet or Haiku keeps you working.

To continue immediately, enable usage credits, which let you keep working past the included allowance at standard API rates. Run /usage-credits after signing in with /login to open the settings. Always set a monthly spend limit while you are there, because an automated task in a loop can generate a bill quickly.

There is a trap attached to this. While you are drawing on usage credits, the prompt cache lifetime drops from one hour to five minutes, so you hit cache misses far more often and pay more for the same work. Set ENABLE_PROMPT_CACHING_1H=1 to keep the one-hour lifetime.

And if you get cut off mid-task, work this sequence instead of typing until everything dies:

  1. Stop asking new questions in that session.
  2. Write a handoff: goal, files changed, decisions, next action.
  3. Run /context to see what is stale and useless.
  4. /compact if the same task must continue; /clear if you are switching.
  5. Move pasted blocks into files and reference the paths.
  6. Check /mcp and disable what you are not using.
  7. Drop to a lighter model for whatever simple work remains.

Keep the priority straight: usage credits are a seatbelt, not a fix. So is upgrading your plan. If the workflow is messy, more allowance just lets you stay messy for a few more days.

If you also use Claude on the web

Because the budget is shared, claude.ai habits directly shrink what your terminal has left. Four things are worth doing:

  • Edit the original prompt instead of sending a correction. In the web UI, the edit control on your own message lets you rewrite and regenerate, so the bad exchange is replaced rather than appended to the history. It is the web version of the no-correction-chains rule above.
  • Start a new conversation every 15–20 messages. If you need continuity, ask for a summary and paste it as the first message of the new chat. You keep what matters and drop the accumulated bulk.
  • Put recurring files in a Project. Upload once there instead of re-attaching the same document to every conversation.
  • Turn off what you are not using. Web search, research mode, connectors, and leave extended thinking off by default, switching it on only when you want longer reasoning. Facts about you ("what I do, how I write") belong in Memory or a .md file rather than being retyped at the start of every chat.

Which three habits should you start with?

This guide is long, so here are the three worth adopting today: run /clear between unrelated tasks; default to Sonnet and call Opus only for planning; and use plan mode (Shift+Tab) before any wide change, because a rejected plan is always cheaper than a wrong diff you have to regenerate. Once those are automatic, come back for the hooks and the fixed-cost trimming, because that is where the next large saving is.

The real difference is how you picture the tool. People who hit the wall constantly run Claude Code like a chat box: one conversation running all week, one default model for everything, everything dumped into the same window. People who rarely hit it run it like an orchestrator: routing work by difficulty, isolating noisy operations in subagents, caching repeated knowledge in files, and treating each session as a scratchpad they can throw away. The gap is wide enough that a Pro plan with good habits often outlasts a Max 5x plan with bad ones.

The more useful realization is not a command at all. Most "I burned through my limit by lunchtime" sessions come from a project Claude cannot navigate, so it searches instead of reading; asking too much is rarely the cause. That makes a full quota a structure problem before it is a model problem.

References

Check yourself

Three quick questions to see whether the main ideas stuck.

  1. Why does usage drop fast even when you type very little?
  2. What is a sensible default for model choice in Claude Code?
  3. Why does a hook beat an instruction in CLAUDE.md for stopping a wasteful pattern?

Share this article

AI glossary