A Few Tips to Cut Claude Code Token Costs
Claude Code requests consist of three token layers: system prompt, project context, and conversation history; most token waste comes from these background layers, not user prompts Prompt caching reduces repeated content to ~10% of standard input rates, but cache invalidation from model switches, effort changes, or prompt prefix modifications can erase those savings CLAUDE.md is the single largest overlooked token sink; keeping it under 200 lines and moving workflow-specific instructions into ski
Analysis
TL;DR
- Claude Code requests consist of three token layers: system prompt, project context, and conversation history; most token waste comes from these background layers, not user prompts
- Prompt caching reduces repeated content to ~10% of standard input rates, but cache invalidation from model switches, effort changes, or prompt prefix modifications can erase those savings
- CLAUDE.md is the single largest overlooked token sink; keeping it under 200 lines and moving workflow-specific instructions into skills or path-scoped rules dramatically reduces per-turn costs
- Conversation compaction, /rewind, and /clear are essential tools for managing growing context, but should be used strategically at task boundaries rather than reflexively
- Output token waste can be controlled through thinking budgets, verbose tool output filtering via PreToolUse hooks, and delegating log-heavy tasks to subagents
Why It Matters
Token costs in Claude Code are driven more by structural context overhead than by actual user requests, making optimization a high-leverage activity for anyone running long or frequent sessions. Understanding prompt caching mechanics and context layer management can reduce bills significantly without sacrificing output quality. These techniques scale from individual developers to team-wide practices, where accumulated waste across many sessions becomes substantial.
Technical Details
- Three-layer request structure: Every Claude Code request stacks (1) system prompt with MCP tool definitions, (2) project context from CLAUDE.md, scoped rules, and skills, and (3) full conversation history. Prompt caching discounts matching prefixes to ~10% of standard input token rates.
- Cache invalidation triggers: Switching models, changing effort levels, enabling fast mode for the first time, and modifying early prompt prefixes all cause cold cache misses. Deferred MCP tool loading was introduced to reduce unnecessary invalidation from server changes.
- Context optimization mechanisms: Skills load instructions only when invoked rather than at session start. Path-scoped rules (using
paths:frontmatter) load only when Claude touches matching files. The/compact,/rewind, and/clearcommands manage conversation growth with different cost profiles. - PreToolUse hooks: Custom scripts can intercept and modify tool inputs before execution, enabling automatic filtering of verbose commands (e.g., appending
grepandheadto test commands) to reduce output token consumption. - Key commands:
/usageshows token consumption and cost estimates;/contextinspects what occupies the context window;/effortcontrols thinking budget;/mcpmanages tool server connections.
Industry Insight
- Organizations running Claude Code at scale should audit CLAUDE.md and rules directories as a first optimization step, since these static context layers are the highest-leverage cost drivers and require no behavioral change beyond restructuring instructions.
- The deferred MCP tool loading architecture signals a broader industry shift toward modular, on-demand context loading rather than monolithic system prompts, which will likely become a standard pattern for agent-based development tools.
- Teams should establish session hygiene norms—using
/clearbetween unrelated tasks, planning before executing, and compacting before breaks—as these zero-cost practices compound into significant savings across many users and sessions.
Disclaimer: The above content is generated by AI and is for reference only.