⚡ Your AI bill is eating your Q4 margin.Protect Your Margin. Get a FREE 360° Cost ReportFree 360° Cost Report

Home › Docs › Claude Code Team Cost Playbook

Control and visibility

Claude Code Team Cost Playbook: Control API Spend Without Slowing Engineers

Telling engineers to “use Claude Code less” trades away your biggest shipping advantage. Runaway coding-agent API bills almost never come from productive coding turns—they come from bloated startup prefixes, un-cleared 200k+ token marathons, expired 5-minute prompt caches, unscoped lockfile/log dumps, and uncapped postpaid keys.

Quick summary

Preserve full engineering velocity with five repo-level and gateway-level controls: keep root CLAUDE.md under 200 lines and avoid mid-session cache invalidators; run /clear between tickets and /compact before 150k–200k tokens; block lockfiles and verbose test dumps in .claude/settings.json; pin exploration subagents to Haiku or Sonnet with right-sized /effort; and enforce prepaid workspace wallets with separate ack_... keys per squad or repo. Model your own team scenarios in the Claude Code API Cost Calculator.

Team cost-control checklist

Commit the first four controls directly into your repository so every developer gets them automatically on git pull, and enforce the fifth at the gateway boundary:

ControlWhere to set itWaste eliminatedDeveloper friction
1. Lean prefix & stable cacheRoot CLAUDE.md (<200 lines) + .claude/skills/20k–40k startup overhead on every session, /clear, and subagent; avoids 25x cold-miss rewritesNone — faster first-token latency
2. Intentional resets (/clear vs /compact)Team habit + CLAUDE_CODE_AUTO_COMPACT_WINDOWSilent 1M-window snowballing past 200k–400k tokens across unrelated ticketsNone — cleaner reasoning & fewer retries
3. Scoped search & quiet test logs.claude/settings.json deny rules + rg flagsLockfiles, dist/ bundles, and 50k-token test stack traces re-sent on every subsequent turnZero — checked into repo once
4. Right-sized /effort & subagent models.claude/agents/*.md (model: haiku) + /effortInherited Opus/Sonnet cold caches on simple file searches and max-effort thinking on routine editsNone — Opus/Sonnet kept for hard design
5. Prepaid wallet & scoped ack_... keysapicuts workspace (/app/funding & /app/keys)Uncapped month-end postpaid invoice shock and invisible cache-miss regressionsZero — native /v1/messages endpoint

1. Keep CLAUDE.md lean and protect prompt-cache hits

Every tool round-trip in Claude Code sends a stateless POST /v1/messages request layered in strict prefix order: System prompt + tool schemas → Project context (CLAUDE.md, auto memory, unscoped rules) → Conversation history + tool results. On Claude Sonnet 5.5 ($2.00 base input) and Claude Opus 5.5 ($4.00 base input), warm prompt-cache reads bill at 0.05x ($0.10/MTok and $0.20/MTok), whereas 5-minute cache writes bill at 1.25x ($2.50/MTok and $5.00/MTok)—a 25x price gap on cached history (see full rate tables in Claude API pricing, and for a turn-by-turn breakdown of those usage fields read why Claude Code burns API tokens so fast).

  • Keep root CLAUDE.md under ~200 lines (~2k–4k tokens). Root CLAUDE.md is loaded into memory at session start. While editing CLAUDE.md mid-session does not immediately bust an active cache, a 35,000-token root file inflates the initial 1.25x cache write on every new session, every /clear, every /compact reload, every cold-cache miss, and every spawned subagent. Move deployment runbooks, PR templates, and domain schemas into on-demand .claude/skills/ or subdirectory CLAUDE.md files that load only when Claude reads files in that subtree.
  • Avoid mid-session prefix invalidators. Switching models mid-thread with /model (including opusplan toggling from Opus in Plan Mode to Sonnet in Execution Mode on a deep history), toggling /fast, adding or removing upfront MCP servers mid-session, or injecting dynamic timestamps via custom system-prompt wrappers invalidates the cached prefix from that layer forward and forces a full cold-cache rewrite.
  • Account for the 5-minute API-key TTL default. On claude.ai subscriptions, Claude Code gets a 1-hour main-chat cache TTL. On API keys, cloud providers, and LLM gateways, Claude Code defaults to a 5-minute TTL for both main sessions and subagents. If an engineer pauses 7 minutes for standup or CI on a 140k-token context, the next prompt triggers a full 1.25x cold-cache rewrite. Train the habit of running /clear when finishing a ticket before a break, or opt into 1-hour caching (CLAUDE_CODE_PROMPT_CACHE_TTL=1h, billed at 2.0x write) specifically for long architecture sessions that pause frequently across an hour.

2. Use /clear between tickets and /compact before 150k–200k tokens

Because Claude Sonnet 5.5, Opus 5.5, Haiku 5.5, and Fable 5.2 default to a 1M-token native context window, Claude Code no longer auto-compacts around 190k tokens out of the box (auto-compaction triggers near ~967k unless configured). Leaving one terminal session open across four unrelated tickets silently drags 200k+ tokens of stale file reads into every tool call and turns every >5-minute pause into an expensive cold-cache rebuild.

  • /clear between every distinct ticket (zero API cost). Run /rename <ticket-id> followed by /clear as soon as a PR goes up. You drop straight back to your lean base prefix at zero summarization token cost, while keeping the old session resumable via /resume if review comments arrive.
  • /rewind when an approach dead-ends (keeps warm cache). If Claude edits three files down the wrong path, use /rewind to jump back to an earlier turn rather than pasting corrective walls of text. Earlier turns sit inside the existing warm prefix cache, avoiding both extra context growth and a summarization call.
  • /compact with focus instructions on multi-stage features. When a single complex migration crosses roughly 120k–160k tokens (check anytime with /context or /usage), run /compact Focus on the database migration schema and failing integration tests. Remember that /compact sends one summarization API call and rebuilds a fresh post-compact prefix (CLAUDE.md + summary + up to 5 recently modified files ≤5k tokens each), so run it while your existing cache is still warm—not right after returning from lunch.
  • Set a repo-wide auto-compact ceiling. Add "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "180000" under env in .claude/settings.json so marathon sessions compact automatically before snowballing into 300k+ contexts.

A single unguarded read of pnpm-lock.yaml, a bundled dist/ file, or a 4,000-line verbose test log appends 40,000+ tokens to conversation history that gets billed on every subsequent turn in the loop. Block generated artifacts in .claude/settings.json and set concise CLI flags in CLAUDE.md:

.claude/settings.json — Repo-shared guardrails
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "180000"
  },
  "permissions": {
    "deny": [
      "Read(./pnpm-lock.yaml)",
      "Read(./package-lock.json)",
      "Read(./Cargo.lock)",
      "Read(./dist/**)",
      "Read(./build/**)",
      "Read(./coverage/**)",
      "Read(./**/*.min.js)"
    ]
  }
}

Pair that file with three explicit lines in root CLAUDE.md:

  • Search specific directories with ripgrep (rg -n "symbol" src/) rather than broad repo dumps.
  • Run tests with quiet failure-only output first (pytest -q --tb=short --maxfail=3 or npm test -- --silent) before inspecting individual failing specs.
  • Read large files with targeted line offsets instead of loading multi-thousand-line fixtures wholesale.

4. Manage /effort thinking budgets and pin subagent models

In Anthropic's Messages API, output_tokens already includes extended-thinking tokens (thinking_tokens), all billed once at the model's output rate ($10.00/MTok on Sonnet 5.5; $20.00/MTok on Opus 5.5; see controlling reasoning token costs). On Claude 5.5 and Fable 5.2 models, thinking is always active and controlled via /effort (low, medium, high, max) rather than an on/off toggle, and the 4.7+/5.x tokenizer emits roughly 30% more tokens for identical code than 4.6 models.

  • Default daily coding to Sonnet 5.5 at medium effort; reserve Opus 5.5 or high/max effort for hard architecture. Avoid flipping /model back and forth inside a 150k-token session (which invalidates the prompt cache); instead, plan complex architecture in a short initial session or separate window, commit the plan doc, and execute cleanly on Sonnet 5.5.
  • Pin read-only subagents to Haiku 5.5 or Sonnet 5.5. Every subagent spawns an isolated context window and its own separate 5-minute cache, and inherits the parent session's model by default. If a lead engineer runs Opus 5.5 ($4/$20) and triggers three codebase-search subagents without a model override, all three subagents pay Opus cold-write ($5.00/MTok) and output ($20.00/MTok) rates. Set model: haiku (claude-haiku-5-5: $0.10/MTok input and $0.50/MTok output up to 100k total prompt tokens—keep subagent context well under 100k, above which Haiku 5.5 steps up 5.0x to $0.50/$2.50) or model: sonnet in .claude/agents/ definitions.
  • Treat experimental agent teams as high-multiplier jobs. Multi-instance agent teams coordinate independent context windows (~7x token consumption vs a single session); reserve them for parallelizable migrations where wall-clock speed justifies the multiplier.

5. Enforce prepaid budgets, per-squad ack_... keys, and cache-ratio checks

Repo hygiene keeps individual sessions lean, while gateway controls guarantee a stuck CI agent or forgotten weekend loop can never produce an uncapped invoice:

Shell — Connect Claude Code to apicuts native /v1/messages
unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://apicuts.ai"
export ANTHROPIC_AUTH_TOKEN="$APICUTS_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-5-5"
claude

See coding tools for full Claude Code, Codex CLI, and macOS Companion setup details, and budgets, limits and alerts for gateway policy behavior:

  • Prepaid workspace wallet hard stop. Create a workspace at /signup and fund a prepaid wallet in /app/funding. Unlike postpaid provider credit lines that bill unexpected overages at month end, apicuts admits requests only while your posted workspace wallet balance is non-negative and rejects subsequent calls cleanly (402 insufficient_wallet) once confirmed funds are exhausted.
  • Separate ack_... company keys per squad, repo, or CI job. Issue distinct named keys in /app/keys for each engineering squad, repository, or automated PR-review workflow so you can scope allowed models and rotate or revoke a single runaway key in seconds. (Note: apicuts company keys are workspace-scoped rather than per-employee seat billing; pair per-squad ack_... keys with Claude Code's /usage command or OpenTelemetry export when you need individual developer machine telemetry.)
  • Audit token categories without logging code. apicuts forwards native Anthropic /v1/messages requests (including 5m/1h cache_control breakpoints, tool calls, and thinking signatures) without storing raw prompts or source code, while recording exact per-request input, cache_read, cache_write_5m, cache_write_1h, and output token counts in /app/overview and /app/requests (explore sample views in the live demo, and check workspace-enabled models via authenticated GET https://apicuts.ai/v1/models). If a key's cache_read share drops below ~70% of total input tokens, look immediately for >5m idle thrash, /model switching, or dynamic system prefixes.

Illustrative worked example: before vs. after on an 8-engineer team

Illustrative workflow scenario — not a guaranteed discount. Both columns model the exact same engineering output: an 8-developer team working 20 days/month, shipping 3 features per developer per day (480 features/month), where each feature takes 30 coding turns + 2 five-turn codebase searches on verified standard Anthropic API list prices for Claude Sonnet 5.5 ($2.00 input, $2.50 5m cache write, $0.10 cache read [0.05x], $10.00 output) and Claude Haiku 5.5 ≤100k ($0.125 5m write, $0.01 cache read, $0.50 output):

Metric / assumptionBefore (unmanaged defaults)After (5-point team playbook)
Session structure (30 turns/feature)1 un-cleared 30-turn marathon (50k → 282k prompt)3 focused 10-turn sprints with /clear (20k → 56k prompt)
Startup prefix & net turn growth42k prefix (bloated CLAUDE.md) + 8k/turn (unscoped logs)16k prefix (<200-line CLAUDE.md) + 4k/turn (scoped rg/tests)
>5m idle cache misses per feature2 cold 5m cache rewrites (turns 12 & 22)0 mid-sprint cold misses (/clear before breaks)
Thinking & subagent config3,000 out/turn; 2 inherited Sonnet 5.5 subagents1,500 out/turn (/effort medium); 2 Haiku 5.5 subagents
Cache-read tokens / feature4,794,000 ($0.4794)1,180,000 ($0.0993)
5m cache-write tokens / feature756,000 ($1.8900)240,000 ($0.4290)
Output + thinking tokens / feature105,000 ($1.0500)55,000 ($0.4550)
Total per feature (tokens / USD)5,655,000 tokens / $3.41941,475,000 tokens / $0.9833
Spend per engineer / active day (3 features)$10.26 / day$2.95 / day
8-engineer monthly total (480 features)$1,641.31 / month ($3,282.62 on Opus 5.5)$471.97 / month (−$1,169.34/mo illustrative delta)

Test your own team size, turn counts, 5m vs 1h cache TTLs, and custom or contracted rate cards in the Claude Code API Cost & Token-Burn Calculator.

Frequently asked questions

What does Claude Code typically cost per developer on an API key?

Anthropic's published Claude Code documentation reports an enterprise average near $13 per active developer day ($150 to $250 per developer per month), with daily spend staying under $30 for roughly 90% of users. Uncompacted 200k+ sessions, frequent 5-minute cache expirations, and Opus subagents are what push outlier sessions much higher.

When should engineers use /clear versus /compact in Claude Code?

Use /clear between unrelated tickets because it resets conversation history immediately at zero API token cost. Use /compact when you are still mid-feature and need Claude Code to summarize architecture decisions and recent edits before context snowballs past 150k to 200k tokens.

Why do API-key teams see more cache-write spikes than subscription users?

On API keys, cloud providers, and LLM gateways, Claude Code defaults to a 5-minute prompt cache TTL rather than the 1-hour main-chat TTL used on claude.ai subscriptions. On Claude Sonnet 5.5 and Opus 5.5, an idle pause longer than 5 minutes turns a 0.05x cache read into a 1.25x cache write, making that cached prefix 25x more expensive on the resumed turn.

Sources: Anthropic API pricing reference, Claude Code cost management docs, and Claude Code prompt caching docs. Standard global API list rates verified November 14, 2026; regional residency (inference_geo: "us", 1.1x) or custom enterprise contracts vary.

Related

Model your team's Claude Code spend or cap it with a prepaid wallet

Run your own session assumptions in our free calculator, explore token breakdowns in the live demo, or create a self-serve workspace with prepaid spend limits.

Open the Claude Code Cost Calculator