Token Usage Reduction

Definition

Practices for reducing the token consumption of LLM coding agents. Token costs scale with context size: every request carries the full conversation history, so the levers are keeping context small and paying cached rates whenever possible.

Key Points

• Cost model: Claude Code bills by API token consumption; enterprise average ≈ $13perdeveloperperactivedayand$150–250 per developer per month, below $30/day for 90% of users. /usage computes a local per-session estimate at standard list rates — an approximation for tracking, not the bill.
• Prompt caching: repeated content (system prompt, history) is re-read at the cached token rate. Cache lifetime is 1 hour on a subscription and 5 minutes on usage credits, API key, or cloud provider. Cache misses reprocess the full context — the first message after a long break is the expensive one.
• Compaction: auto-compaction summarizes conversation history near the context limit; /compact accepts custom instructions (/compact Focus on code samples and API usage) and a project-level # Compact instructions block in CLAUDE.md. Compacting a large context is itself a large request; /clear costs nothing.
• Model selection: default to Sonnet for most coding, reserve Opus for complex architectural decisions or multi-step reasoning, and assign model: haiku to simple subagents.
• Context hygiene: /clear between unrelated tasks (stale context taxes every later message), /rename before clearing so /resume can restore the session, and delegate verbose operations (tests, documentation fetches, log processing) to subagents so only summaries return.
• Structural levers: MCP tool definitions are deferred by default (names only until the tool is used) — prefer CLI tools and disable unused servers; code-intelligence plugins replace grep-plus-read with go-to-definition; hooks preprocess large inputs (a 10,000-line log can shrink to hundreds of tokens); skills load domain knowledge on demand while CLAUDE.md stays under 200 lines.
• Extended thinking: billed as output tokens, with default budgets that can reach tens of thousands per request; lower via /effort, disable in /config, or cap with MAX_THINKING_TOKENS on fixed-budget models. Adaptive-reasoning models ignore nonzero budgets — use effort levels there; some models (Fable 5) cannot disable thinking.
• Agent teams: each teammate runs its own context window; plan mode uses roughly 7× the tokens of a standard session. Keep teams small, keep spawn prompts focused, and shut teammates down when done.
• Prompting habits: specific prompts avoid broad scanning; plan mode and early course-correction (Esc, /rewind) prevent expensive re-work; verification targets and incremental testing catch errors when they are cheap.
• Compression tools are not free: proxies that compress input (tool output, command output) can push cost the other way. RTK’s own issue #582 measured an 18% cost increase — compressed input forced Claude to write ~50% more output tokens to compensate, and output is billed at ~5× the input rate on Opus-class models. Measure total cost, not token counts; tools like headroom add output-token shaping and token-optimizer-mcp measure savings against a control arm to close the loop.^[raw/external/github-com-f7d4988e.md]
• Diagnose waste sources before choosing a tool: agents waste context in recognizable places (terminal logs, full files, repeated grep loops, old state, verbose replies, unnecessary code), and each waste source has a different fix. Ask “where is my agent actually wasting context?” rather than “which tool saves the most tokens?” — see token-waste-sources for the taxonomy and measurement checklist.
• Repo navigation is its own lever: a local code map (symbols, callers, dependencies) lets the agent ask once instead of grep-plus-open loops, cutting tool calls and file reads rather than compressing bytes; vendor benchmark reports 58% fewer tool calls and ~zero file reads across 7 repos (see codegraph).
• Rate limits are the org-level cost ceiling: per-user TPM/RPM tiers scale inversely with team size — 1–5 users: 200–300k TPM / 5 req/s; 5–20: 100–150k / 2.5–3.5; 20–50: 50–75k / 1.25–1.75; 50–100: 25–35k / 0.62–0.87; 100–500: 15–20k / 0.37–0.47; 500+: 10–15k / 0.25–0.35. Limits apply at org level (e.g., 200 users → 20k TPM each, 4M total).
• MCP tool schemas re-enter context on every message (not per session): a typical 4-server setup carries roughly 7,000 tokens/message of tool definitions; heavier multi-server configs reach 15–20k tokens per turn, and complex servers can exceed 50k before a single prompt. With MCP servers central to Claude Code workflows, this can dominate input spend — a large, distinct slice from the client-side deferral documented in tool-context-management.
• The gateway is the fleet-level lever: a gateway like bifrost moves tool governance and orchestration out of the prompt — servers appear as Python stubs the model reads on demand, scripts run in a sandbox, and per-tool virtual keys mean unauthorized tools are never injected (zero token cost). Vendor benchmark: 58% / 84% / 92% input-token reduction at 96 / 251 / 508 tools (see code-mode-orchestration; self-published, independent measurement pending).
• MCP overhead has a primary-source cost model: a single tool definition runs 100–500 tokens; 10–15 well-documented tools ≈ 1,500–4,000/turn; a 30-tool server with rich schemas can hit 5,000–8,000; three-to-four-server setups land at 12,000–20,000 tokens/turn before the first query — the ~18,000 figure is a “realistic mid-range estimate,” not worst case. Claude Code’s 200k window loses nearly 10% of effective working space to tool schemas alone on such a setup.^[raw/prompts/articles/mindstudio-claude-code-mcp-token-overhead.md] This independently corroborates the 15–20k/turn range previously cited from Bifrost.
• MCP tool schemas are re-sent every message, never cached: the FAQ is explicit that there is no cross-turn caching of tool definitions at the API level — each API call carries the full schema alongside history. So the fix is architectural (fewer/shorter schemas, gateway, or capability-calling), not something prompt caching can amortize.
• Audit before you prune: a 4-step process — list every server in ~/.claude/settings.json and project .claude/settings.json, count tools per server via the tools/list endpoint, estimate cost with tokens ≈ (tools × 200) + (description_chars ÷ 4), then sort to find the 2–3 offenders that carry most of the overhead. Server pruning (anything unused in 2 weeks), project-level configs over a bloated global one, source-level description trimming (60–80 tokens/tool saved; 3,000–4,000/turn across 50 tools), and tool filtering/lazy loading are the main levers.
• /usage attribution: the plan breakdown attributes usage % to skills, subagents, plugins, and MCP servers, flagging any behavior ≥10% of usage; d/w toggles 24h/7d windows; the rate-limited endpoint shows “last-known usage” bars over a 60-minute window. /usage resets on /clear (v2.1.211+).
• Background usage: typically <$0.04 per session (summarization, /usage status checks) — a minor but real recurring cost.
• CLAUDE.md → skills migration: move workflow instructions out of CLAUDE.md into on-demand skills to cut the per-session fixed context, complementing the “under 200 lines” rule.

Implications

Token cost is a context-engineering problem, not just a model-selection problem. The cheapest fixes are behavioral (clear, rename/resume, specific prompts) and structural (caching, hooks, skills, subagents) rather than settings-driven. Organizations should measure with /usage before wide rollout, and treat extended-thinking budgets and plan-mode agent teams as the largest controllable multipliers.^[raw/prompts/articles/claude-code-costs-reduce-token-usage.md] The official costs doc adds the operational layer: rate-limit tiers as a hard ceiling and /usage attribution for locating the ≥10% cost drivers.

Contested: input-compression proxies do not reliably reduce cost (see rtk-rust-token-killer); the input/output billing asymmetry makes any input-only optimizer suspect until measured end-to-end.

Open Questions

• Whether the 1-hour vs 5-minute cache-lifetime distinction remains current as pricing evolves; the claim is version-sensitive. (See prompt-caching for API-level write/read multipliers.)
• Whether model: haiku in subagent configuration preserves output quality on non-trivial subagent tasks.
• Whether the rate-limit tiers remain current as plans evolve; the table is version-sensitive.
• Whether the Bifrost 58–92% input-token reductions hold under independent measurement, and whether gateway-enforced tool visibility measurably beats client-side tool search on already-lean toolsets.
• Whether capability-as-method-calls (MindStudio-style) degrades as the number of capabilities grows, since the agent must still know the method names without schema discovery.

Related

claude-code-system-prompt — the agent these cost levers apply to claude-3 — model family; Sonnet/Opus/Haiku cost tiers llm-settings-and-parameters — sampling and extended-thinking knobs reasoning-effort — API-level effort control on OpenAI models, analogous to /effort ai-agents-guide — context engineering and agent-team design prompt-caching — API mechanism behind the cached-rate lever claude-code-environment-variables — programmatic pins for these levers (token budgets, caching) claude-code-sessions — session hygiene primitives (/clear, resume-from-summary) claude-code-memory — CLAUDE.md/auto-memory context budget tool-context-management — client-side and gateway strategies for tool-definition bloat code-mode-orchestration — gateway pattern for scripting tool calls in a sandbox token-waste-sources — the diagnostic taxonomy for choosing among reduction tools capability-as-method-calls — execution-outside-the-prompt alternative to schema injection

The captured technique index is a link-oriented inventory of model, session, caching, output, and prompt-design levers. It complements the operational evidence above, but individual links still require separate verification before being treated as current guidance.

Sources

• raw/prompts/articles/claude-code-costs-reduce-token-usage.md
• raw/prompts/token-reduction-techniques.md
• raw/external/code-claude-com-costs-ea267c0e.md
• raw/prompts/articles/bifrost-mcp-gateway-claude-code-token-costs.md
• raw/prompts/articles/mindstudio-claude-code-mcp-token-overhead.md
• raw/prompts/articles/reduce-wasted-tokens.md
• raw/external/github-com-f7d4988e.md
• raw/external/github-com-headroom-cbd05f4e.md