Claude Code Costs: Cut Token Usage and Stretch Limits

To cut Claude Code costs, keep the context small and use the cheapest model and effort level that can do the job. Every request re-sends the whole conversation. Anthropic's docs say that unexpectedly high spend on an API or cloud-provider plan usually comes from long sessions that were never cleared or from Opus left as the default model. Below: how to see where your usage goes, which habits matter most, and which controls a team lead has on each type of plan.

The details come from Anthropic's Claude Code documentation on costs and prompt caching. Commands and plan details change between versions, so run claude --version and check the docs if something on your screen doesn't match.

How Claude Code costs and usage limits work

Claude Code is billed by API token consumption. What that means for you depends on how you sign in:

• Pro and Max (individual subscriptions): usage is included in the plan, up to its limits. Past a limit, you can turn on usage credits to keep working.
• Team and Enterprise: each member's Claude Code usage comes out of a per-seat allowance that resets on a rolling five-hour window and a weekly window. The allowance is shared with Claude chat and Cowork, and its size depends on the seat tier (Standard or Premium).
• Claude Console (API key): billed per token to your organization, with workspace spend limits.
• Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry: billed per token to your cloud account. Spend controls are your cloud provider's budget tools.

For scale, Anthropic reports an average across enterprise deployments of about $13 per developer per active day and $150–250 per developer per month, with 90% of users staying under $30 per active day. Your numbers will depend on model choice, codebase size, and how much you run in parallel or in automation. Anthropic recommends a small pilot group to establish a baseline before a wider rollout.

Measure first: /usage, /context and /insights

/usage opens with a Session block showing token counts by model (input, output, cache read, cache write) and a dollar figure. Claude Code calculates that figure locally at list price, so treat it as an estimate; authoritative billing is on the Usage page in the Claude Console. Since v2.1.211 the Session totals reset when you run /clear. From v2.1.251 there is also a Prompt cache (main) line with the share of input served from cache, the number of misses, and whether the cache is warm right now. It covers the main conversation only, not subagents.

On a subscription, the session dollar figure doesn't affect your bill. On Pro, Max, Team and Enterprise plans, what matters is the plan usage bars and the breakdown below them:

• Attribution: the share of recent usage from skills, subagents, plugins and individual MCP servers.
• Behavior flags: patterns such as long context or cache misses, flagged when one accounts for 10% or more of recent usage, each with a tip for reducing it.
• Loops: the heaviest /loop and other scheduled tasks, with total and per-run tokens (v2.1.242 or later).

Press d or w to switch between the last 24 hours and the last 7 days. The breakdown is approximate and built from session history on your machine, so it leaves out usage from other devices and from claude.ai.

/context shows what is taking up the context window right now. Use it when sessions feel expensive and you don't know why.

/insights writes an HTML report on how you work: what you work on, friction points such as misunderstood requests or buggy code, and suggestions. The latest report is saved to ~/.claude/usage-data/report.html. The analysis itself counts against your plan or API usage.

The habits that save the most

The docs name two habits as the highest-impact: clearing between unrelated tasks and matching the model to the job.

Use /clear between unrelated tasks

Claude Code sends the full conversation with every request, plus another request each time Claude uses tools. Prompt caching bills re-reads at the lower cached-token rate, but a one-line question in a session that has been open all day still draws usage for the whole conversation.

When you move to unrelated work, start fresh:

/rename auth-refactor
/clear

/rename lets you find the old session later with /resume. /clear costs nothing. /compact sends a request containing the whole conversation to produce a summary. While the cache is warm, most of that is read from cache, but after a break longer than the cache lifetime it reprocesses the full history as uncached input. Compact at a natural break when you need continuity; clear when you don't. If you went down a path you want to abandon, /rewind to an earlier turn instead: it goes back to a prefix that is already cached.

If you do compact, tell it what to keep:

/compact Focus on code samples and API usage

You can also put standing compaction instructions in CLAUDE.md:

# Compact instructions

When you are using compact, please focus on test output and code changes

Match the model to the task

The docs say Sonnet handles most coding tasks well and costs less than Opus, and recommend reserving Opus for complex architectural decisions or multi-step reasoning. Switch mid-session with /model, or set a default in /config.

Three things are easy to miss:

• Switching to Opus also switches the subagents that inherit your session's model.
• For simple subagent tasks, set model: haiku in the subagent's configuration. For more on when subagents are worth it, see Claude Code Subagents: When to Split Work and How.
• Each model has its own prompt cache, so a mid-session model switch makes the next request reprocess the whole conversation. Pick the model at the start of a session where you can.

Lower effort for simple work

Extended thinking is on by default, and thinking tokens are billed as output tokens. Depending on the model, the default budget can be tens of thousands of tokens per request. For routine work, lower the effort level with /effort or in /model, or disable thinking in /config. Opus 5.5, Sonnet 5.5, Haiku 5.5 and the Fable models always use extended thinking and can't have it turned off, so effort is the setting to adjust there.

Changing effort mid-session also has a cache cost on most models: the next request reprocesses the conversation. The exception is Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 used with an API key or a Claude subscription, where the cache is kept (not on Bedrock, Google Cloud's Agent Platform or a Claude apps gateway).

On models with a fixed thinking budget, you can also lower it with an environment variable:

MAX_THINKING_TOKENS=8000

Adaptive-reasoning models ignore nonzero budgets, so use effort levels with those instead.

Write specific prompts and plan before building

A vague prompt like "improve this codebase" triggers broad scanning. "Add input validation to the login function in auth.ts" lets Claude read only what it needs. For bigger changes:

• Press Shift+Tab to cycle to plan mode, so Claude proposes an approach for your approval before writing code. Re-work after a wrong first direction is expensive.
• Press Escape as soon as Claude heads the wrong way. Use /rewind or double-tap Escape to restore an earlier checkpoint.
• Give it verification targets such as test cases or expected output, so Claude catches its own mistakes before you have to ask for fixes.

Shrink the context Claude starts with

Anything loaded at session start is carried in every request of that session.

• Keep CLAUDE.md short. The docs suggest staying under 200 lines and moving workflow-specific instructions, such as PR reviews or database migrations, into skills, which load only when invoked. Our CLAUDE.md best practices covers what belongs in the file.
• Trim MCP servers. MCP tool definitions are deferred by default, so only tool names and server instructions enter context until a tool is used. Still, run /mcp and disable servers you aren't using. Where a CLI exists (gh, aws, gcloud, sentry-cli), it is more context-efficient than an MCP server because it adds no per-tool listing.
• Install code intelligence plugins for typed languages. One "go to definition" call can replace a grep followed by reading several candidate files.

Filter noisy output before Claude reads it

Test runners and logs fill context fast. A PreToolUse hook can rewrite a command so Claude sees only what matters. This is the example from the docs, which pipes test output through a filter for failures. Add it to settings.json:

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

Create the folder with mkdir -p ~/.claude/hooks, save the script as ~/.claude/hooks/filter-test-output.sh, and make it executable with chmod +x:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# If running tests, filter to show only failures
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

Run /hooks and check that it appears under PreToolUse. Another option is to delegate verbose jobs such as test runs, documentation fetches and log processing to a subagent, so only a summary returns to your main conversation. The subagent's own requests still count against your usage, so give it a smaller model.

Why usage climbs in a long session

If your limits drain faster than your activity seems to justify, check these:

• Cache misses after breaks. On a subscription, within plan usage, the main conversation's prompt cache lasts an hour. It drops to five minutes once you're drawing on usage credits, and five minutes is the default on API keys and cloud providers. The promptCacheTtl setting (v2.1.242 or later) lets you choose 1h yourself; one-hour cache writes are billed at a higher rate. Your first message after a longer break reprocesses the full context. On Pro and Max, Claude Code offers to resume a large session from a summary after a long break.
• Scheduled tasks and loops fire on their interval while the session is idle, and each run sends your full context.
• Subagents send their own requests on top of the main conversation's, and get a five-minute cache by default even on a subscription. The attribution breakdown in /usage shows their share.
• Agent teams. Each teammate has its own context window, and the docs estimate about 7x the tokens of a standard session when teammates run in plan mode. Teams are off by default. If you enable them, keep teams small, use Sonnet for teammates, and shut teammates down when they finish.
• Background requests, such as summarizing past conversations for claude --resume, are small: typically under $0.04 per session.

Hitting a limit: what each message means

• "You've hit your session limit" / "weekly limit": a subscription usage window shared across all models, so switching models won't help. Wait for the reset time shown, or run /usage-credits if usage credits are turned on.
• "You've hit your Opus limit" / "Sonnet limit": model-specific. Switching to a model outside that family with /model lets you keep working.
• Spend limit messages (individual, org monthly, or team shared budget): usage credits have reached a cap an admin set. An admin raises it under Organization settings > Usage.
• Auto-compact warnings aren't usage limits. They mean the conversation is close to its auto-compact window.

Controls for team leads

• Team and Enterprise: the org analytics spend report shows estimated spend per user and per model, with CSV export. It covers usage-credit spend and appears once usage credits are on; usage inside the seat allowance isn't metered in dollars. With usage credits on, spend limits can be set per organization, group or member.
• Console: set workspace spend limits. A "Claude Code" workspace is created automatically the first time someone authenticates with a Console account. For organizations with custom rate limits, a workspace rate limit on it caps Claude Code's share so it can't crowd out other production workloads.
• Cloud providers: Anthropic's analytics don't cover this usage. For per-user attribution, use OpenTelemetry export, a self-hosted Claude apps gateway, or an LLM gateway.
• Contracted rates: the modelPricing managed setting (v2.1.242 or later) makes the figures in /usage, the status line and OpenTelemetry reflect your contracted prices instead of list price. It changes what Claude Code reports, not what you are charged.

If you run several agents in parallel, budget for each one, because every session has its own context. On Atlas, where each engineer is its own Claude Code session with model and effort tuned to its role, an optional daily budget warns at 50% and 80% and pauses the team at 100%.

Summary

Most Claude Code spend comes from context you no longer need and from models or effort levels set higher than the task requires. Clear between tasks, default to Sonnet, lower effort for routine work, keep CLAUDE.md and MCP lean, and filter noisy output before Claude reads it. Then check the /usage breakdown over the last 7 days to see which changes made a difference.