Home › Docs › Claude Code Team Cost Playbook
Control and visibilityClaude 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.
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:
| Control | Where to set it | Waste eliminated | Developer friction |
|---|---|---|---|
| 1. Lean prefix & stable cache | Root CLAUDE.md (<200 lines) + .claude/skills/ | 20k–40k startup overhead on every session, /clear, and subagent; avoids 25x cold-miss rewrites | None — faster first-token latency |
2. Intentional resets (/clear vs /compact) | Team habit + CLAUDE_CODE_AUTO_COMPACT_WINDOW | Silent 1M-window snowballing past 200k–400k tokens across unrelated tickets | None — cleaner reasoning & fewer retries |
| 3. Scoped search & quiet test logs | .claude/settings.json deny rules + rg flags | Lockfiles, dist/ bundles, and 50k-token test stack traces re-sent on every subsequent turn | Zero — checked into repo once |
4. Right-sized /effort & subagent models | .claude/agents/*.md (model: haiku) + /effort | Inherited Opus/Sonnet cold caches on simple file searches and max-effort thinking on routine edits | None — Opus/Sonnet kept for hard design |
5. Prepaid wallet & scoped ack_... keys | apicuts workspace (/app/funding & /app/keys) | Uncapped month-end postpaid invoice shock and invisible cache-miss regressions | Zero — 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.mdunder ~200 lines (~2k–4k tokens). RootCLAUDE.mdis loaded into memory at session start. While editingCLAUDE.mdmid-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/compactreload, every cold-cache miss, and every spawned subagent. Move deployment runbooks, PR templates, and domain schemas into on-demand.claude/skills/or subdirectoryCLAUDE.mdfiles that load only when Claude reads files in that subtree. - Avoid mid-session prefix invalidators. Switching models mid-thread with
/model(includingopusplantoggling 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.aisubscriptions, 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/clearwhen finishing a ticket before a break, or opt into 1-hour caching (CLAUDE_CODE_PROMPT_CACHE_TTL=1h, billed at2.0xwrite) 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.
/clearbetween every distinct ticket (zero API cost). Run/rename <ticket-id>followed by/clearas 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/resumeif review comments arrive./rewindwhen an approach dead-ends (keeps warm cache). If Claude edits three files down the wrong path, use/rewindto 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./compactwith focus instructions on multi-stage features. When a single complex migration crosses roughly 120k–160k tokens (check anytime with/contextor/usage), run/compact Focus on the database migration schema and failing integration tests. Remember that/compactsends 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"underenvin.claude/settings.jsonso marathon sessions compact automatically before snowballing into 300k+ contexts.
3. Scope file searches and keep build/test output out of context
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:
{
"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=3ornpm 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
mediumeffort; reserve Opus 5.5 orhigh/maxeffort for hard architecture. Avoid flipping/modelback 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. Setmodel: haiku(claude-haiku-5-5:$0.10/MTokinput and$0.50/MTokoutput 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) ormodel: sonnetin.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:
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"
claudeSee 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/keysfor 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-squadack_...keys with Claude Code's/usagecommand or OpenTelemetry export when you need individual developer machine telemetry.) - Audit token categories without logging code. apicuts forwards native Anthropic
/v1/messagesrequests (including5m/1hcache_controlbreakpoints, tool calls, and thinking signatures) without storing raw prompts or source code, while recording exact per-requestinput,cache_read,cache_write_5m,cache_write_1h, andoutputtoken counts in/app/overviewand/app/requests(explore sample views in the live demo, and check workspace-enabled models via authenticatedGET https://apicuts.ai/v1/models). If a key'scache_readshare drops below ~70% of total input tokens, look immediately for >5m idle thrash,/modelswitching, 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 / assumption | Before (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 growth | 42k prefix (bloated CLAUDE.md) + 8k/turn (unscoped logs) | 16k prefix (<200-line CLAUDE.md) + 4k/turn (scoped rg/tests) |
| >5m idle cache misses per feature | 2 cold 5m cache rewrites (turns 12 & 22) | 0 mid-sprint cold misses (/clear before breaks) |
| Thinking & subagent config | 3,000 out/turn; 2 inherited Sonnet 5.5 subagents | 1,500 out/turn (/effort medium); 2 Haiku 5.5 subagents |
| Cache-read tokens / feature | 4,794,000 ($0.4794) | 1,180,000 ($0.0993) |
| 5m cache-write tokens / feature | 756,000 ($1.8900) | 240,000 ($0.4290) |
| Output + thinking tokens / feature | 105,000 ($1.0500) | 55,000 ($0.4550) |
| Total per feature (tokens / USD) | 5,655,000 tokens / $3.4194 | 1,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