Claude Code Usage Limits: Check, Audit, and Reduce Token Usage

On a Pro or Max plan, Claude Code draws from two allowances at once: a session limit that resets every five hours and a weekly limit that resets at a fixed time assigned to your account. Run /usage to see both bars and when each one resets. /cost and /stats are aliases that open the same screen. /status shows version, model, account, and connectivity, so use it to confirm which account you are on, not to read what is left.

When a bar climbs faster than the work seems to justify, a bigger plan is rarely the first fix. A long Claude Code session usually drains for an ordinary reason: carried context, a cache rebuild, a verbose MCP server, or subagents. A short audit shows which one. Then you can apply the reduction that matches and pace heavy days so the weekly allowance does not run out while the five-hour window still has room.

Commands and behavior below are as of October 5, 2026, from Anthropic's Claude Code cost documentation, command reference, and Help Center. Claude Code changes quickly. If a field or menu differs, run claude --version and go by your installed version.

Where to check Claude Code usage: /usage, /status, and Settings > Usage

/usage is the in-terminal answer to "how much is left and when does it reset." The other surfaces answer different questions, and mixing them up makes a correct number look wrong.

The Session block counts tokens for the current session and prices them locally at list rates. Anthropic's docs state that for Max and Pro subscribers this figure "isn't relevant for billing purposes," so a $40 estimate on a Max plan is not a $40 charge. Since v2.1.211 the totals reset when /clear starts a new session. Since v2.1.251 the block also carries a Prompt cache (main) line with the share of input served from cache, the number of misses, and whether the cache is warm.

On Pro, Max, Team, and Enterprise plans, /usage adds a breakdown of what counts against your plan limits. It attributes recent usage to skills, subagents, plugins, and individual MCP servers. It flags behaviors such as long context or cache misses when one accounts for 10% or more of recent usage, and since v2.1.242 it lists the heaviest /loop and scheduled tasks. The breakdown is computed from session history on this machine, so it misses claude.ai and your other computers. If the plan-limit request fails, /usage shows the last bars it loaded within the past 60 minutes with a Showing last-known usage note. Press r to retry.

Anthropic's own Help Center article on using Claude Code with Pro or Max, dated August 19, 2026, still says to monitor remaining allocation with /status. The Claude Code command reference describes /status as version, model, account, and connectivity, and its limit-error guidance says to run /usage to see plan limits and reset times. Use /usage for the allowance and /status for the account.

That account check matters. If an ANTHROPIC_API_KEY environment variable is set, Claude Code uses that key instead of your subscription, and the work is billed as API usage rather than drawn from your plan. On an API key or a cloud provider there is no hard stop: the account is charged per token, /usage shows running spend for the session, and the Console or cloud dashboard is the bill. The Claude Code API billing vs subscription guide covers how to tell which one is active and how to switch.

How the 5-hour session limit and the weekly limit work together

The two limits fill at the same time. Every request counts against the session allowance and the weekly allowance together, so waiting out a five-hour reset refills only one of them. Anthropic's error reference puts the risk plainly: "A single burst of heavy activity, such as a large workflow fanout, can exhaust the weekly allowance before the session window resets."

What the Claude Pro and Claude Max plan pages state:

• The session-based limit resets every five hours.
• The weekly limit applies across all models. It resets at a fixed day and time assigned to your account, which stays the same no matter when you start working. Settings > Usage shows the next reset.
• Max (formerly Max 5x) includes five times the Pro plan's usage every five hours and every week. Ultra (formerly Max 20x) includes ten times Pro's usage every week and has no five-hour limit for verified accounts. Max costs $100 and Ultra $200 per month, and Pro is $20 per month in the US.
• Anthropic may also limit usage in other ways, such as weekly and monthly caps or model and feature usage.

Usage is shared across claude.ai, Claude Code, Claude Desktop, and the Claude Code extensions for VS Code and JetBrains IDEs. A long chat in the browser draws from the same pool as your terminal. How much a request uses depends on conversation length, features, model, and effort level. Anthropic does not publish a number of hours or prompts per window, and it does not document whether the five-hour window starts with your first message. Read the reset time instead of counting from your first prompt.

When a window runs out, Claude Code shows one of these messages with the reset time:

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
You've hit your Sonnet limit · resets 3:45pm

The session and weekly limits are shared across all models, so switching models does not restore access. The Opus and Sonnet limits apply only to that model family. Before a window runs out, Claude Code can warn you with a message such as You've used 85% of your session limit · resets 3:45pm.

Why Claude Code hits usage limits so fast

Claude Code sends your full conversation with every request, and each tool call sends another request carrying its results. Prompt caching makes those re-reads cheaper, but cached re-reads still draw usage. A one-line question late in an all-day session pays for the whole conversation behind it.

Anthropic's cost guide lists the usual reasons a long session uses more than your activity suggests:

• Cache misses after a break. Your first message after a gap longer than the cache lifetime reprocesses the full context. The lifetime is one hour on a subscription. It drops to five minutes while you draw on usage credits, and it is five minutes by default on an API key or cloud provider.
• Requests sent while you are idle. Scheduled tasks fire on their interval, messages from your other sessions arrive as new turns, and an active goal can trigger up to three idle check-ins between your prompts. Each one sends your full context.
• Subagents, workflows, and agent teammates. Each agent sends its own requests on top of the main conversation. Agent teams use roughly 7 times the tokens of a standard session when teammates run in plan mode.
• Model and effort. Opus uses more than Sonnet for the same work. Thinking tokens are billed as output, and thinking cannot be turned off on Opus 5.5, Sonnet 5.5, or the Fable models.
• Compaction itself. /compact reads the conversation it summarizes, so compacting a large context is a large request. /clear costs nothing.

Background jobs such as summarizing sessions for --resume add a small amount, typically under $0.04 per session. Each of these causes is normal on its own. The question is which one dominates your session, and that takes a few recorded numbers.

Build one audit ledger while the session is still open

Keep the suspect session open. Record claude --version, then run /usage, /context, and /mcp. Copy these fields into a private note. Do not paste API keys, customer code, private prompts, or full transcripts into a support ticket.

Separate context growth from cache churn

Context and cache are related, but they are different meters. Context is what each request carries. Caching changes the rate for the part of that request that matches what the API processed recently. A growing session can cost more per turn even when caching works perfectly.

Run /context and look for the largest categories. Startup context includes CLAUDE.md, memory, MCP tool names, and skill descriptions. File reads, tool results, and conversation messages pile up as work continues. A session that wandered through three unrelated tasks pays for all three on every new message.

For caching, read the token classes separately:

• cache_read_input_tokens: an existing prefix was reused at the cheaper cached rate.
• cache_creation_input_tokens: a prefix was written or rebuilt.
• Plain input: content that was not served from cache.
• Output: generated work, which caching does not discount.

A single cache write after a known change is normal. Anthropic's prompt-caching guide lists the triggers: switching models (including each plan-mode toggle under opusplan), changing effort on most models, turning on fast mode, connecting or removing an MCP server when tools load upfront, compacting, removing old images, upgrading Claude Code, and idling past the cache lifetime. On Opus 5.5, Sonnet 5.5, Fable 5.1, and Fable 5.2 (released November 9, 2026) with an API key or a Claude subscription, changing effort keeps the cache.

The stronger signal is repeated high cache creation with low reads across similar turns. The Prompt cache (main) line in /usage counts misses for you, and since v2.1.260 it can name a likely cause, such as likely cause: tool definitions changed. It covers the main conversation only, not subagents. For TTL details and how to prove a miss, see the Claude Code cache TTL and token usage guide.

Audit MCP in two layers: definitions and returned data

Do not multiply the number of connected servers by a guessed token cost. On supported models, Claude Code defers MCP tool definitions through tool search, so only tool names and server instructions enter context until Claude uses a specific tool. Tool search can be unavailable, for example through a custom ANTHROPIC_BASE_URL gateway, and then definitions load upfront.

That leaves two places to look:

1. Definitions and discovery. /mcp and /context show which servers are active and what they add before any work starts.
2. Returned data. A small tool definition can still return a huge database dump or log that stays in conversation history and rides along on every later request.

The /usage attribution counts an MCP server's share only for requests that consumed one of its tool results. Claude Code warns when one MCP result exceeds 10,000 tokens, and the default maximum is 25,000 tokens, adjustable with MAX_MCP_OUTPUT_TOKENS. A larger result is saved to a file and replaced in the conversation by its path. Raising the limit does not make results cheaper. Filter, paginate, or summarize at the source instead. The Claude Code MCP context overload guide walks through the cleanup.

Run a clean control session before you escalate

A control session turns a feeling into a comparison. Pick one small task that resembles the expensive work without exposing sensitive data.

1. Keep the same sign-in method, model, effort, project, and Claude Code version.
2. Start a new session and enable only the MCP servers the task needs.
3. Record /usage and /context before work.
4. Run one bounded task with a clear completion condition.
5. Record the same fields afterward.
6. Compare context growth, cache writes and reads, output, attribution, and API time.

If the control is cheap, the original session was carrying history, large tool results, unrelated work, or extra agents. The next section maps each pattern to a fix.

If the control reproduces the spike with the same settings, stop repeating it and keep the ledger. A strong report to Anthropic support says: same version, sign-in method, model, effort, project, and small task; fresh session; no MCP change; timestamps and token classes attached; the disproportionate result reproduced once. Subscribers reach support from claude.ai by clicking their initials and choosing Get help.

Reduce Claude Code usage with the fix that matches the cause

Pick the row that matches what the audit showed. Applying every tip at once makes it impossible to tell which one helped.

A few habits cut usage in every session because they shrink what each request carries. Name the file and function instead of asking Claude to "improve the codebase," which triggers broad scanning. Reference files by path rather than pasting them. The @ prefix injects the whole file plus its CLAUDE.md tree, so a bare path is cheaper when you only need part of it. Use plan mode before changes that touch more than a few files, and press Esc or /rewind as soon as Claude heads the wrong way.

Plan a heavy day or week around the 5-hour and weekly limits

The weekly limit is usually the one that ends a heavy week, because waiting a few hours refills only the session bar. Budget the weekly allowance, and use the five-hour window to pace each day.

Check both bars before a big task. Run /usage and note both percentages and reset times. A large workflow fan-out, an agent team, or a /batch run starts many agents at once, and that kind of burst can drain the weekly allowance before the session window resets.

Compare the weekly bar with the share of the week that has passed. Divide the days since your weekly reset by 7. If your weekly percentage is higher than that share, you are spending faster than an even pace. For example, three days after the reset, 3 ÷ 7 ≈ 43% of the week has passed. A weekly bar at 60% leaves 40% for four days, or about 10% per day.

Test expensive patterns small. Run one subagent or one batch unit first and compare the weekly bar in /usage before and after. Multiply that step by the number of units in the full run, and scale up only if the remaining weekly headroom covers it.

Keep usage visible in the status line. You do not need a third-party monitor to watch both windows. On Pro and Max, the status line receives rate_limits.five_hour and rate_limits.seven_day, each with used_percentage and resets_at in Unix epoch seconds. The fields appear only after the first API response in a session, and either window can be absent. Save this script as ~/.claude/statusline.sh and make it executable with chmod +x. It needs jq.

#!/bin/bash
input=$(cat)
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
RESET=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

OUT=""
if [ -n "$FIVE_H" ]; then
  OUT="5h: $(printf '%.0f' "$FIVE_H")%"
  [ -n "$RESET" ] && OUT="$OUT, resets in $(( (${RESET%.*} - $(date +%s)) / 60 ))m"
fi
[ -n "$WEEK" ] && OUT="${OUT:+$OUT | }7d: $(printf '%.0f' "$WEEK")%"
echo "${OUT:-plan usage not reported yet}"

Then point Claude Code at it in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

With both windows present, the line reads like 5h: 23%, resets in 94m | 7d: 41%. Before the first response it prints plan usage not reported yet. The script was run with sample input under macOS bash and jq. It was not run inside a live Claude Code session.

Close the idle senders before you step away. Stop /loop tasks you do not need, and know that an active goal can send check-ins while you are gone. Setting CLAUDE_CODE_GOAL_CHECKIN_MINUTES to 0 turns those off. On Pro and Max, when you resume a large session after a long break, Claude Code offers to resume from a summary so later requests do not carry the full history.

Decide what should happen at the limit before you leave a session running. That choice is covered in the next section.

What happens when you hit the session or weekly limit

Claude Code blocks further requests until the reset time in the message. /rate-limit-options shows the ways to keep going: wait and continue automatically, add usage credits, or upgrade. Which option fits depends on which limit you hit.

Automatic continue. While it waits, the bottom of the session shows Usage limit reached · limit resets 3:45pm and Continuing automatically at 3:45pm · esc to cancel. After the reset, Claude Code prompts Claude to pick the task up where it stopped. It does not resend your last message. Permission prompts still appear, so an unattended task can stall on one. If it hits the limit again, it re-arms at most twice in a row and then stops. Press Esc to cancel one wait. To turn the behavior off, disable Continue automatically at usage limit in /config, or set autoContinueAtUsageLimit to false in your user settings. The Desktop app has a separate Auto-continue when limits reset checkbox on the session-limit card, so turn each off on its own.

Usage credits. On Pro and Max you enable them in Settings > Usage, set a monthly spend limit or choose unlimited, and prepay funds. /usage-credits opens that page and works only when you signed in with your claude.ai subscription, not an API key. While credits are on, /usage shows this month's credit spend against your limit, and the session limit still resets every five hours. For the cost math, see Claude extra usage cost. For how credits, cloud session credit, and limit resets differ and which to use first, see Claude cloud session credit vs usage credits vs limit reset.

Pay-as-you-go for a sprint. Anthropic's Pro and Max help article also lists switching to a Claude Console account and buying API credits for intensive coding sprints. That moves the work onto per-token billing with no hard stop, so set a workspace spend limit in the Console first.

If you are deciding whether a bigger plan is worth it, the Claude Pro vs Max guide compares the tiers against Claude Code workloads, and the Claude Code pricing guide lists current plan prices. If you are staring at the exact "Rate limit reached" message, the Claude Code rate limit reached fix guide is the recovery checklist.

Claude Code usage limit questions

How can I view the Claude Code token usage dashboard?

On an individual Pro or Max plan, /usage is the dashboard. It shows the session block, plan bars, and a 24-hour or 7-day breakdown, and Settings > Usage on claude.ai shows the same windows. On Team and Enterprise, admins get an analytics dashboard and a spend report in org analytics. API customers use the Console usage page and its Claude Code dashboard.

Does the Claude Code 5-hour window start with my first prompt?

Anthropic says the session limit resets every five hours and shows the time remaining, but it does not document when the window starts. Read the reset time in /usage, Settings > Usage, or the limit message instead of counting from your first prompt. The weekly reset is fixed to your account and does not move with your activity.

Does switching to Sonnet get me past the Claude Code weekly limit?

No. The session and weekly limits are shared across all models. Switching families helps only with the separate Opus limit or Sonnet limit, and the switch costs one full uncached re-read of the conversation.

Is a 429 or 529 error the same as hitting my Claude Code usage limit?

No. A plan limit names the session, weekly, Opus, or Sonnet limit and shows a reset time. A 529 means the service is overloaded. A 429 on an API key comes from that account's API rate limits. Each has its own fix, linked in the reduction table above.