Claude Code · AI costs ·

Claude Code usage limits: how to reduce token usage so they last (Pro and Max)

If Claude Code says you've hit your limit before the day is out, the cause is often how much context each request carries, not how many prompts you typed. This post explains what draws on your Pro or Max limits, how to see it before you run out, and the settings and habits that can help reduce Claude Code token usage. It ends with a status line, a hook and a subagent file you can copy.

This guide pairs with Ship-Ready AI Rules, and if you want the next step, read Supabase getSession vs getUser vs getClaims: which to use where.

Checked 17 Oct 2026 on Claude Code 2.1.302. Everything about limits and commands comes from Anthropic's own docs and help articles, linked in Sources. Claude Code changes most weeks, so check claude --version against the version above.

What we did and didn't test. We ran no Claude subscription for this post, so we measured no real plan usage and can't say how much any tip saves. We tested the config offline: the status line script against sample input in the documented format, the hook against sample test output, the subagent file with claude plugin validate, and the settings files as valid JSON. Without signing in we couldn't run slash commands, so every one named here was checked against the built-in command list in Claude Code 2.1.302, and what they do comes from Anthropic's docs. We aren't affiliated with or endorsed by Anthropic; Claude and Claude Code are its trademarks, used here only to identify them.

How Claude Code usage limits work on Pro and Max

Anthropic's help centre describes two limits on paid plans:

  • A five-hour session limit. It resets every five hours.
  • A weekly limit. It resets once a week. Max plans also have a separate weekly limit for Fable models.

These limits are shared: what you do in Claude on the web, desktop or mobile and in Claude Code all counts against the same limits. Anthropic doesn't publish the limits as token numbers, so watch the percentage bars in Claude Code and under Settings > Usage on claude.ai.

Two recent official changes are worth knowing:

  • Weekly limits. A promotion raised Claude Code weekly limits by 50% from 13 May to 13 September 2026. From 14 September, Anthropic says weekly limits in Claude Code are 25% higher than they were before the promotion, on Pro, Max, Team and seat-based Enterprise plans. The promotion didn't change five-hour limits. If your weekly bar fills sooner than it did in August, the end of that promotion is the documented change; we found no official cut to the limits in October.
  • Wrap-up allowance. If you reach the five-hour limit partway through a response, Claude Code may keep working briefly to finish the step in progress. You'll see "Usage limit reached · wrapping up". It's small and capped, counts toward your weekly limit, needs Claude Code 2.1.277 or later, and is rolling out gradually. On Pro it applies up to once per weekly period.

The session and weekly limits are shared across all models, so switching models with /model won't restore access once you've hit one. A model-specific message, such as "You've hit your Opus limit", is different: switching to another model family does let you keep working.

What actually uses your limit

Claude Code sends your whole conversation with every request. Each time Claude uses a tool, another request goes out carrying that batch of tool results. So a one-line question in a session that's been open all day still draws on your limit for the whole conversation, although prompt caching means the repeated history is billed at the cached rate.

Anthropic's cost docs list the usual reasons usage climbs in a long session:

  • Long context. Files Claude has read, pasted logs and tool output all stay in the conversation.
  • Cache misses. Your first message after a break longer than the cache lifetime reprocesses the full context. On a subscription the lifetime is an hour. It drops to five minutes once you're drawing on usage credits.
  • Subagents and agent teams. Each one sends its own requests on top of the main conversation.
  • Scheduled tasks. A scheduled task fires on its interval even while you're away, sending the full context each time.
  • Compaction. /compact reads the conversation it summarizes, so compacting a large context is itself a large request.

Effort level and model choice matter too. The help centre lists both as factors in how fast you use your limit, and says higher effort uses more tokens.

See your usage before you hit the wall

In Claude Code 2.1.302, /usage is the command to use. Its built-in description reads "Show session cost, plan usage, and activity stats", and /cost and /stats are aliases for it. Some help articles still point to /status for your allocation, but in 2.1.302 its description is "Show Claude Code status including version, model, account, API connectivity, and tool statuses". On a Pro or Max plan, /usage shows your plan usage bars plus a breakdown of recent usage:

  • Attribution. The share used by skills, subagents, plugins and individual MCP servers.
  • Behaviour flags. Things like long context or cache misses, flagged when one accounts for 10% or more of recent usage.
  • Loops. The heaviest scheduled tasks.

Press d or w to switch between the last 24 hours and the last 7 days. The breakdown comes from local session history on that machine, so it doesn't include claude.ai or other devices. The dollar figure in the Session block is meant for API users; on a subscription it isn't what you're billed.

Run /context to see what's filling the context window right now.

A status line that shows your 5-hour and weekly use

The status line gets a JSON object on stdin. For Pro and Max subscribers it includes a rate_limits object with a five_hour and a seven_day window, each with a used percentage from 0 to 100 and a reset time in Unix seconds. It only appears after the session's first response, and each window can be absent, so the script has to cope with missing fields.

Save this as ~/.claude/statusline.sh and make it executable with chmod +x. It needs jq.

#!/bin/bash
# Status line for Claude Code: model, context %, 5-hour and 7-day plan usage.
# rate_limits only appears for Pro/Max subscribers, after the first response.
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name // "?"')
CTX=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty' | cut -d. -f1)
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty' | cut -d. -f1)
RESET=$(echo "$input" | jq -r '.rate_limits.five_hour.resets_at // empty')

OUT="[$MODEL] ctx ${CTX}%"
[ -n "$FIVE_H" ] && OUT="$OUT | 5h ${FIVE_H}%"
[ -n "$RESET" ] && OUT="$OUT (resets $(date -d "@$RESET" +%H:%M 2>/dev/null || date -r "$RESET" +%H:%M))"
[ -n "$WEEK" ] && OUT="$OUT | week ${WEEK}%"
echo "$OUT"

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

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

We fed it sample input built from the documented schema (5-hour window 23.5% used, 7-day window 41.2%). This is its real output on our box, run with TZ=UTC; the reset time is shown in the machine's local time zone:

[Opus] ctx 8% | 5h 23% (resets 10:00) | week 41%

With an API key there's no rate_limits object, so it prints only the model and context share. We tested both cases, plus a case with only the five-hour window present, using sample input. We haven't seen it run against a live subscription.

/clear vs /compact: when to use which

Anthropic's rule of thumb is to use /clear when starting a new task and /compact when continuing a long one.

  • /clear starts a new session with empty context. The cost docs say it costs nothing. Your CLAUDE.md and project files are still available, and the old session stays on disk, so you can get back to it with /resume. Use /rename first if you want to find it easily.
  • /compact replaces the history with a summary, which keeps continuity but is itself a large request on a big context. You can tell it what to keep by adding instructions after the command:
/compact Focus on the failing tests

You can also put a "Compact instructions" section in CLAUDE.md.

A quick test from the help centre: if your next prompt would make sense in a brand-new terminal, clear before sending it.

Claude Code also has idle compaction, added in 2.1.299. If a conversation of 200,000 tokens or more sits idle for about 54 minutes on the one-hour cache, Claude Code compacts it just before the cache expires, so your next message sends a summary instead of reprocessing everything. It's on by default. If you'd rather keep the full history, turn it off from the Idle compaction row in /config, or set this in settings.json:

{
  "idleCompaction": false
}

Match the model and effort to the job

Anthropic's guidance is that Sonnet handles most coding tasks well and costs less than Opus, with Opus kept for complex architecture or multi-step reasoning, and Haiku for quick mechanical work. Switch with /model mid-session without losing the conversation. /model opusplan uses Opus in plan mode and Sonnet for execution.

For simpler tasks, lower the effort level with /effort. Some models always use extended thinking, so on those the effort level is the setting to change.

Run the Explore subagent on Haiku

Claude Code's built-in Explore subagent handles codebase search. By default it uses your main conversation's model. If that's a Fable model and you're on a Claude subscription, the sub-agents docs say it runs on the Opus model that the opus alias resolves to. A user or project subagent named Explore overrides the built-in and keeps its own model field. Save this as .claude/agents/Explore.md in your project, or in ~/.claude/agents/ for all projects:

---
name: Explore
description: Read-only codebase search and file discovery. Use when you need to find files, symbols or patterns without changing anything.
tools: Read, Grep, Glob
model: haiku
---
Search the codebase and report back what you found: file paths, line numbers and a short summary. Don't edit files. Keep the summary short and only include what the caller asked for.

Check that the frontmatter parses with:

claude plugin validate .claude/agents

On 2.1.302 it printed "✔ Validation passed". Haiku may miss things in a large or unusual codebase that Opus would find, so try it on your own repo first. To default other subagents to a cheaper model, set CLAUDE_CODE_SUBAGENT_MODEL. A subagent's own model field still takes precedence over it.

Keep always-loaded context small

CLAUDE.md is loaded into context at the start of every session. Anthropic suggests keeping it under about 200 lines, with essentials only, and moving detailed workflow instructions into skills, which load only when they're needed.

Two other things in the docs:

  • MCP servers. Tool definitions are deferred by default, but CLI tools like gh still use less context. Run /mcp and disable servers you aren't using.
  • Point at files instead of pasting. Anything you paste stays in context for the rest of the session. A bare path such as src/auth.ts lets Claude read selectively. The help centre notes that the @ prefix injects the whole file.

Trim test output with a hook

Test runs are a common source of long tool output. Anthropic's cost docs include a PreToolUse hook that rewrites test commands so only failures come back. This is that hook with the runners changed for a typical JavaScript project. Save it as trim-test-output.sh in ~/.claude/hooks/ and make it executable:

#!/bin/bash
# PreToolUse hook (Bash): when Claude runs the test suite, keep only failures.
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

if [[ "$cmd" =~ ^(npm test|npm run test|pnpm test|npx vitest run) ]]; then
  filtered="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "ask", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

Register it in settings.json:

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

We fed the hook sample hook input for npm test, npx vitest run and an unrelated command. The test commands came back rewritten with the other input fields kept, and the unrelated one was left alone. We then ran the filter against a sample test run with one failure: the failure and its assertion line stayed and the passing files were dropped.

Two caveats. The filter hides passing output, so Claude can't see warnings you might want. And permissionDecision: "ask" shows you the rewritten command before it runs. Run /hooks to check it's registered.

When you do hit the limit

  • Wait. The limit message shows when the window resets. The docs say Claude Code can wait and continue the interrupted task after the reset; /rate-limit-options is where you manage that.
  • Usage credits. Run /usage-credits to turn on or request credits and keep working past the limit at API rates. Remember the cache lifetime drops to five minutes while you're on credits, so long pauses cost more.
  • Check for a stray API key. If ANTHROPIC_API_KEY is set in your environment, Claude Code uses it instead of your subscription, and you're billed at API rates.

If you use Claude through the API, with a Console key in Claude Code or in your own app, you pay per token, so cache hits matter. Our post on prompt caching not working shows how to check whether a request hit the cache. If your app calls the API on behalf of your users, per-user spend limits in Next.js covers capping what each user can spend. If you want a rough monthly figure for API use, you can enter your tokens per request, cached share and traffic in our AI API cost calculator; it gives estimates only.

Checklist

  • Add the status line so you can see the 5-hour and weekly bars as you work.
  • Run /clear between unrelated tasks; use /compact only to continue a long one.
  • Use Sonnet for routine work, Opus for planning or hard problems, and lower /effort on simple tasks.
  • Put an Explore subagent on Haiku if it finds what you need in your repo.
  • Keep CLAUDE.md short and move workflows into skills.
  • Disable MCP servers you aren't using.
  • Point at file paths instead of pasting files or long logs.
  • Trim test output with a hook.
  • Check /usage for flagged behaviours.
  • Make sure ANTHROPIC_API_KEY isn't set unless you mean to use the API.

Related

Disclosure: this is our own paid product. If you build on Next.js, Supabase and Stripe, Ship-Ready AI Rules ($19 plus VAT where applicable) is a Claude Code plugin with 3 guardrail hooks, 18 stack-specific skills and 6 subagents, plus Cursor rules and AGENTS.md. It isn't a usage-saving tool, and we haven't measured its effect on your limits.

Sources (checked 17 October 2026):

Related posts