How Claude Code Usage Limits Work, and How to Cut Your Token Usage

If you have hit a Claude Code usage limit after what felt like a handful of prompts, you are not imagining it. The five-hour session window and the weekly cap draw from the same pool as your regular Claude.ai chats and Cowork sessions, and Anthropic’s own cost guidance points out that a single heavy debugging session can outweigh an entire day of ordinary chat use, since a coding turn carries file contents, tool calls, and multi-step reasoning that a plain chat message does not. One long conversation, one large parallel workflow, or an afternoon spent pasting whole files instead of the relevant lines can drain a budget that would otherwise last for days.

This guide breaks down how the limits actually work, where the tokens go during a normal session, and which habits and settings genuinely change the outcome. Most of it comes down to paying attention to numbers Claude Code already shows you, not finding a clever way around them.

The two clocks that control your access

Claude Code enforces two allowances at the same time. The session limit is a rolling five-hour window. It starts counting from your first prompt and clears five hours later, not at a fixed clock time. The weekly limit sits above it and resets on a fixed day assigned to your account. Both draw on the same underlying allowance, and usage counts against both at once, so a single burst of heavy activity, such as a large parallel workflow, can exhaust your weekly allowance before the session window has even reset.

When you hit one, Claude Code tells you exactly when it clears:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

The session and weekly limits are shared across every model, so switching with /model will not restore access to either one. The Opus limit works differently: it only covers Opus requests, so dropping to Sonnet with /model gets you working again immediately.

The allowance itself is also shared more broadly than most people expect. It covers Claude Code, the Claude.ai chat interface, and Cowork together, and its size depends on your seat tier rather than one number that applies to everyone. A long research session in the regular Claude.ai chat window already eats into what is left for your afternoon in the terminal.

Why nobody can give you an exact token number anymore

Search around and you will still find posts estimating a Pro plan at somewhere around 44,000 tokens per five-hour window, with the Max tiers scaled up from there. Treat numbers like that as dated, third-party estimates rather than official figures. Anthropic’s current documentation deliberately avoids advertising a fixed count, because how much a developer actually spends depends heavily on which model they run, how large the codebase is, and habits like keeping several sessions or automated jobs going at once. The one hard number Anthropic does publish: across enterprise deployments, average cost lands around $13 per developer per active day, and 90% of users stay under $30 a day.

The reliable way to check your own number is to run /usage inside a session. It shows your current plan bars, when each one resets, and a breakdown of what recently consumed the allowance, attributed by skill, subagent, plugin, and MCP server, so you can see which specific piece of your setup is the expensive one.

Where the tokens actually go

Every message you send re-sends the entire conversation so far: the system prompt, your project’s CLAUDE.md, every prior message, and every tool result. Prompt caching is what keeps this affordable. The API matches the start of each new request against what it cached from the one before, and only the new material at the end gets processed at full price. A cache hit costs a fraction, roughly a tenth, of what a full-price input token costs, which is why a long-running session is far cheaper per turn than its raw size would suggest, right up until something breaks the match.

A specific set of actions invalidates that cache and forces a full, expensive re-read: switching models with /model, changing the effort level, turning on fast mode partway through a session, an MCP server connecting or disconnecting when its tools load directly into the prompt, denying an entire tool, running /compact, or upgrading Claude Code itself. Editing a file, changing permission mode, invoking a skill, and rewinding the conversation all leave the cache intact, so none of those cost you a rebuild.

Cache lifetime matters just as much as what breaks it. On a subscription, Claude Code requests a one-hour cache window by default, so a coffee break will not force a full re-read. It only drops to five minutes once you have gone past your plan’s usage limit and are drawing on paid usage credits, and even then you can hold the one-hour window by setting ENABLE_PROMPT_CACHING_1H=1 as an environment variable.

Beyond caching, Anthropic’s own guidance names the specific reasons a long session climbs faster than your activity would suggest: the full history gets resent with every tool call, a break longer than the cache window means the next message reprocesses everything from scratch, a scheduled task fires on its own timer and sends full context each time it runs, and a live agent-team member keeps drawing on the budget for as long as it stays active, even when it is doing very little. None of that is a bug. It is the direct cost of keeping a long, stateful conversation alive.

Codebase exploration adds its own tax on top of all this. Developers on the Claude Code subreddit have described the first few minutes of a new task, when the agent reads a dozen or more files just to understand what it is looking at, as the single most expensive stretch of an entire session, sometimes costlier than the fix that follows it. That is an anecdotal pattern rather than an official figure, but it lines up with a simple mechanical fact: Claude has to read a file before it can reason about it, and a ten-thousand-line file costs the same to read whether you plan to touch one line of it or fifty.

Small habits that make the real difference

None of these require new tooling. They are mostly a matter of interrupting a default.

• Clear between unrelated tasks. Run /rename to label a session before you leave it, then /clear to start the next task with nothing to re-read. Stale history from a finished task gets billed on every message of the next one.
• Write prompts that name the file and the function. A request like “improve this codebase” forces Claude to scan broadly before it can act; “add input validation to the login handler in auth.ts” lets it work from a narrow, known starting point.
• Use Plan Mode before a large change. Press Shift+Tab to switch into it. Claude explores and proposes an approach for a few thousand tokens instead of writing, testing, and rewriting hundreds of lines because the first direction was wrong.
• When Claude gets something wrong, resist the instinct to type a conversational correction. A follow-up like “no, only fix section 3” stacks on top of the mistake and forces a second full generation. Double-tap Escape or run /rewind to restore the checkpoint before the error and try again from there.
• Match the model to the task. Sonnet handles most day-to-day coding well and costs less than Opus, which is worth reserving for genuinely hard architectural calls. For a subagent doing simple, well-defined work, set model: haiku in its configuration rather than inheriting the parent’s model by default.

Set these once and stop thinking about them

A handful of configuration choices pay for themselves across every future session, not just the current one.

Keep CLAUDE.md short. Anthropic’s own guidance suggests staying under roughly 200 lines and moving anything workflow-specific, like a database migration procedure or a release checklist, into a Skill instead. A skill only loads into context when it is actually invoked; a bloated CLAUDE.md gets billed at the start of every single session whether that day’s task needs it or not. On a genuinely large codebase, a single root-level file also stops being useful. Layering smaller, directory-specific CLAUDE.md files closer to the code they describe keeps each one relevant to what Claude is actually touching that session.

MCP servers are convenient, but every connected tool has to be described in the request. Where a CLI tool already covers the job, such as gh for GitHub or aws for AWS work, it is more context-efficient than an equivalent MCP server, since Claude can run it directly without a tool listing attached. Run /mcp periodically and disconnect anything you configured once and stopped actually using.

A PreToolUse hook can filter noisy command output before it ever reaches the model. A test suite that produces ten thousand lines of passing-test noise for one real failure is a common offender. A short script that greps for FAIL or ERROR and returns only the relevant lines can cut that particular cost from tens of thousands of tokens down to a few hundred, and Anthropic’s own documentation ships a working example of exactly this pattern for filtering test output. Installing a code intelligence plugin for a typed language has a similar effect at a different layer: it gives Claude precise “go to definition” navigation instead of a blind grep across the repository followed by reading several candidate files to find the right one.

If you use agent teams, keep them small on purpose. Anthropic’s own cost documentation notes that a team running in plan mode uses roughly seven times the tokens of a standard session, since each teammate maintains its own separate context window. That multiplier is fine for a task that genuinely benefits from parallel review; it is expensive overhead for something one focused session could have handled alone.

How to check your own numbers

Guessing at optimization is a waste of the very budget you are trying to protect. Claude Code has native tools for this that most people never open.

/usage is the fastest check: a live breakdown of the current session’s spend, plus, on a paid plan, what fraction of your recent usage came from a specific skill, subagent, or MCP server, and a flag for any single behavior, such as long context or repeated cache misses, that accounts for 10% or more of recent activity. /insights goes further, analyzing up to your last 200 sessions on that machine and writing an HTML report to ~/.claude/usage-data/report.html that surfaces recurring friction, like requests that needed clarifying or code that kept failing review.

For a team, native local commands only cover one machine at a time. OpenTelemetry export streams session counts, token totals, and cost per user into whatever observability stack your organization already runs, and it works the same way regardless of whether developers authenticate through a subscription, the Console, or a cloud provider. If you just want a fast terminal view without setting up an observability pipeline, ccusage is a popular open-source CLI that parses your local session logs offline and prints daily and per-session cost breakdowns. It is not an Anthropic product and has not been reviewed by Anthropic, so treat it, like any third-party tool that reads your local Claude Code data, with the same care you would give any script from outside your organization.

What to actually do when you hit the wall

Once the limit lands, your options are narrower, but they are still worth knowing before it happens rather than while you are staring at the error.

1. Read the reset time in the message itself. It is exact, and Claude Code will not accept further requests until that moment regardless of what you try.
2. If it is specifically the Opus limit, switch models with /model. Session and weekly limits will not budge this way, but the Opus-only cap will.
3. Run /usage-credits to keep working past the allowance. On a Pro or Max plan this opens your usage-credit settings directly; on Team or Enterprise it either opens your organization’s usage settings or sends a request to an admin, depending on your billing access.

You will also find community-built scripts, such as unsnooze and similar auto-resume tools, that watch for the reset timestamp in the limit error and automatically send a “continue” once it passes. These are not part of Claude Code and Anthropic does not maintain them, so running one unattended, especially overnight with your account actively signed in, deserves the same caution you would give any third-party script with standing access to your credentials. A separate tip that circulates in the same threads, using a scheduled routine with a minimal prompt to somehow reset or influence usage counters, has no confirmation behind it beyond anecdote. I would not build a workflow around it.

For teams and API integrations, a different set of limits applies

Everything above covers the subscription-plan session and weekly windows. If you are calling the Claude API directly, whether from Claude Code on the Console, a custom integration, or a cloud provider, you are on a completely different system: per-minute rate limits measured in requests per minute, input tokens per minute, and output tokens per minute, enforced per model class at the organization level. Exceeding any one of the three returns a 429 error naming which limit you hit, along with a retry-after header telling you exactly how long to wait.

A few details are worth building into any production integration from the start. Only uncached input tokens count against your ITPM limit, so a high cache-hit rate effectively raises your usable throughput well above the raw number on your account. Usage tiers advance automatically as your organization’s cumulative spend crosses each threshold, so a workload that gets rate-limited today may simply outgrow the problem in a few weeks without any configuration change. And when a request does get rejected, exponential backoff with a randomized jitter, rather than an immediate retry, is what keeps a wave of failed requests from retrying in lockstep and tripping the same limit again a few seconds later.

If you are rolling Claude Code out to a team on the Console rather than through seat-based subscriptions, Anthropic publishes starting-point recommendations for per-user rate limits, scaled down as the team grows since fewer people tend to be active at exactly the same moment in a larger organization:

Full details on how the tiers, the rate-limit headers, and workspace-level caps fit together are in Anthropic’s API rate limits reference and the shorter support explainer on the same system.

I would start with /usage, not a third-party tool or a workaround script. It takes about ten seconds to tell you whether you are fighting a genuinely tight plan, a bloated CLAUDE.md, or a session that has simply been left open since yesterday, and that answer decides which part of this guide is actually worth acting on next.