​

Track your costs

​

Using the /usage command

Total cost:            $0.55
Total duration (API):  6m 20s
Total duration (wall): 6h 33m 10s
Total code changes:    0 lines added, 0 lines removed
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

​

Prompt cache statistics

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

• Misses: requests that re-processed content the cache already held, with the time of the last miss and how many tokens those requests wrote back to the cache. Actions that invalidate the cache lists the usual causes. When Claude Code can identify a likely cause for the last miss, the line names it too, for example likely cause: tool definitions changed. The likely-cause text requires Claude Code v2.1.260 or later.
• Expected rebuilds: when Claude Code has itself just rewritten the conversation, by compaction or by clearing old tool results from context, it counts the same kind of miss as an expected rebuild instead. This part appears only after at least one expected rebuild has happened.
• Warm or cold: whether the cached prefix is still within its cache lifetime, with the TTL in effect. When the cache is cold, the line shows how long the session has been idle. When no response has reported cache tokens, the line ends with no prompt caching reported by the API instead.

​

Plan usage breakdown

• Attribution: recent usage attributed to skills, subagents, plugins, and individual MCP servers, each shown as a percentage of the total. An MCP server’s share counts only the requests that consumed one of its tool results. Before v2.1.222, after one call to an MCP server, Claude Code attributed every subsequent request to that server, overstating its share.
• Recommendations: suggested changes, one per row. Each row starts with a share of your recent usage, at least 10%, as in 25% Trim ~/code/api/CLAUDE.md · 49k tokens per request.
  • How to read the share: it tells you how much of your usage the row applies to, not how much the change saves. One request can count toward several rows, so the shares can add up to more than 100%.
  • How to apply recommendations: to have Claude Code apply the ones it can, see Apply recommendations with the fix shortcut
• Loops: a row for each of the heaviest /loop or other session-scoped scheduled tasks that ran recently, ordered by total tokens, with a count of the rest. Requires Claude Code v2.1.242 or later.
  • What each row reports: how often the task fires, how many times it ran, its total and per-run tokens, and when it last ran
  • Stopped and re-created loops: Claude Code keys a row by the task’s prompt, so a loop you stop and re-create stays one row

​

Apply recommendations with the fix shortcut

1. After any turn in progress ends, Claude Code runs each /effort command shown in a row without run.
2. Claude then gets one prompt with a step for each of the other rows it can act on. The prompt asks Claude to show you each change before making it.

​

Check your usage-credits spend

• Pro and Max: your spend for the current month, measured against your monthly spend limit when you have set one. When you haven’t set a limit, the row shows Unlimited and no spend figure.
• Team and Enterprise: your own spend for the current month, measured against any limit your organization set that applies to you. A limit that covers the whole organization doesn’t appear in the row. When you have no limit of your own, the row shows your spend with no limit beside it. While usage credits are off for you, /usage shows no usage-credits row.

​

When the usage request fails

​

Read the token count beside the spinner

• What it covers: output the turn generates, such as the text and tool calls Claude streams back, its thinking, and the output of subagents that run in the foreground
• What it leaves out: what Claude Code sends to the model, so your prompt, the conversation history, and the rest of your context don’t move it
• When it resets: at the start of each turn, and when Claude Code compacts the conversation
• When it stays hidden: until output starts arriving, when the row is too narrow to fit it, and in screen reader mode

​

Analyze your usage patterns

​

Add usage credits to your subscription

​

Manage costs for your organization

​

Report spend at your contracted rates

​

Claude for Teams and Enterprise

• See spend: the spend report in org analytics shows estimated spend per user and per model, with CSV export, updated daily. The report covers usage-credit spend and appears once usage credits are turned on. Usage inside the seat allowance isn’t metered in dollars.
• See adoption: the analytics dashboard shows daily active users, sessions, and contribution metrics, with CSV export of contribution data. See track team usage with analytics.
• Cap spend: the seat allowance is the default ceiling. To let members continue past it, turn on usage credits and set spend limits at the organization, group, or individual member level.
• Pull per-user numbers: on the Enterprise plan, the Enterprise Analytics API returns per-user usage and cost reports across Claude surfaces, including Claude Code. A Primary Owner creates a key with the read:analytics scope at claude.ai/analytics/api-keys. On the Teams plan, export the spend report CSV, which lists token usage and estimated spend per user and per model.

​

Claude Console

​

Rate limit recommendations

​

Cloud providers

• OpenTelemetry: export metrics from each developer’s machine to your own observability stack. This gives you per-user token counts, costs, and tool activity regardless of provider.
• A Claude apps gateway: a self-hosted Claude apps gateway provides per-user usage attribution, OTLP metrics with token counts, and per-user spend limits on these providers.
• An LLM gateway: route all Claude Code traffic through a proxy that tracks spend per key. Several large enterprises reported using LiteLLM, an open-source tool that tracks spend by key. This project is unaffiliated with Anthropic and has not been audited for security.

​

When a developer asks about a limit

• “You’ve hit your session limit” or “You’ve hit your weekly limit”: a seat-based usage window on a subscription plan, shared across all models, so the developer can’t restore access by switching models with /model. The message shows when the window resets. After the model-specific “You’ve hit your Opus limit” or “You’ve hit your Sonnet limit” message, switching to a model outside that family with /model does keep the developer working. See usage limit errors. What the developer can do in the meantime:
  • Run /usage-credits to request usage beyond the allowance, if you have usage credits turned on.
  • On Claude Code v2.1.234 or later, wait and continue the interrupted task automatically after the reset; that section lists when Claude Code starts the wait on its own and when the developer picks it from /rate-limit-options. To control for your fleet whether Claude Code starts that wait on its own, set autoContinueAtUsageLimit in managed settings.
• “You’ve hit your individual spend limit”, “org’s monthly spend limit”, or “team’s shared budget”: the developer’s request would be billed to usage credits, and those credits have reached a spend limit you set. To let the developer continue, go to Organization settings > Usage and increase the limit the message names. When the message also names a plan reset time, the developer can instead wait until then. See the error reference for each variant.
• A spend limit message from a Claude apps gateway: the developer passed a spend cap you set on your self-hosted gateway, and the gateway blocks their requests until the period resets or you raise the cap. See gateway spend limits for caps, reset schedules, and the message the developer sees.
• A context or auto-compact warning: not a usage limit. The conversation has grown close to the session’s auto-compact window, the threshold where Claude Code summarizes older history to free space. Point the developer at reduce token usage.
• Unexpectedly high spend on an API or cloud-provider plan: usually traces back to long sessions that were never cleared or to Opus left as the default model. The highest-impact habits to share are clearing between unrelated tasks and matching the model to the job, both covered in reduce token usage.

​

Agent team token costs

• Use Sonnet for teammates. It balances capability and cost for coordination tasks.
• Keep teams small. Each teammate runs its own context window, so token usage is roughly proportional to team size.
• Keep spawn prompts focused. Teammates load CLAUDE.md, MCP servers, and skills automatically, but everything in the spawn prompt adds to their context from the start.
• Shut down teammates when their work is done. Each active teammate continues consuming tokens until it exits or the session ends.
• Agent teams are disabled by default. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings.json or environment to enable them. See enable agent teams.

​

Reduce token usage

​

Manage context proactively

• Clear between tasks: Use /clear to start fresh when switching to unrelated work. Stale context wastes tokens on every subsequent message. Use /rename before clearing so you can find the session later, then /resume to return to it.
• Add custom compaction instructions: /compact Focus on code samples and API usage tells Claude what to preserve during summarization.

# Compact instructions

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

​

Choose the right model

​

Reduce MCP server overhead

• Prefer CLI tools when available: Tools like gh, aws, gcloud, and sentry-cli are still more context-efficient than MCP servers because they don’t add any per-tool listing. Claude can run CLI commands directly.
• Disable unused servers: Run /mcp to see configured servers and disable any you’re not actively using.

​

Install code intelligence plugins for typed languages

​

Offload processing to hooks and skills

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

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

# If running tests, filter to show only failures
pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'
if [[ "$cmd" =~ $pattern ]]; 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", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

​

Move instructions from CLAUDE.md to skills

​

Adjust extended thinking

​

Delegate verbose operations to subagents

​

Manage agent team costs

​

Write specific prompts

​

Work efficiently on complex tasks

• Use plan mode for complex tasks: Press Shift+Tab to cycle to plan mode before implementation. Claude explores the codebase and proposes an approach for your approval, preventing expensive re-work when the initial direction is wrong.
• Course-correct early: If Claude starts heading the wrong direction, press Escape to stop immediately. Use /rewind or double-tap Escape to restore conversation and code to a previous checkpoint.
• Give verification targets: Include test cases, paste screenshots, or define expected output in your prompt. When Claude can verify its own work, it catches issues before you need to request fixes.
• Test incrementally: Write one file, test it, then continue. This catches issues early.

​

Background token usage

• Conversation summarization: Background jobs that summarize previous conversations for the claude --resume feature
• Command processing: Some commands like /usage may generate requests to check status

​

Why usage climbs in a long session

• Long context: Claude Code sends your full conversation with every request, and each time Claude uses tools it sends another request carrying that batch of tool results. With prompt caching, Claude Code re-reads that history at the cached token rate, so a one-line question in a session that has been open all day still draws usage for the whole conversation. See Manage context proactively for ways to keep your context small
• Cache misses: your first message after a break longer than the cache lifetime misses the cache and reprocesses your full context. See which lifetime your requests get and the controls for setting it
• Scheduled tasks: a session-scoped scheduled task fires on its interval even while the session is idle, sending your full context each time
• Cross-session messages: Claude Code delivers a message from another of your sessions as a new turn when this session sits idle, sending your full context each time. To hold inbound messages instead of delivering them, set crossSessionInbound to hold
• Goal check-ins: while background work keeps an active goal waiting, Claude Code asks Claude to check on that work even when the session sits idle, starting a new turn that sends your full context. Claude Code starts at most three idle check-ins per goal between your prompts. Before v2.1.246, idle check-ins were uncapped. To turn check-ins off, set CLAUDE_CODE_GOAL_CHECKIN_MINUTES to 0. Idle check-ins require Claude Code v2.1.236 or later
• Subagents and workflows: every subagent, and every agent a dynamic workflow spawns, sends its own requests on top of the main conversation’s. The attribution breakdown shows the subagent share
• Agent teammates: each active teammate keeps consuming tokens until it exits
• Compaction: /compact reads the conversation it summarizes, so compacting a large context is itself a large request. When you want a fresh start instead of continuity, /clear costs nothing

​

Understanding changes in Claude Code behavior

• Subscription plans (Pro, Max, Team, Enterprise): sign in at claude.ai, click your initials in the lower left, and select Get help
• Console (API) billing: sign in at platform.claude.com, click your initials, and select Get help