Cost and Token Economics

How Claude Code tracks, estimates, and optimizes token usage and cost. The system operates on three levels: real-time cost tracking per session, token estimation for threshold decisions, and architectural optimization for prompt cache economics.

Cost tracking

The cost tracker (src/cost-tracker.ts) accumulates per-model usage after every API response:

Pricing tiers

Web search: $0.01 per request across all tiers. Unknown models default to Opus standard pricing.

What's tracked

Per model: inputTokens, outputTokens, cacheReadInputTokens, cacheCreationInputTokens, webSearchRequests, costUSD, contextWindow, maxOutputTokens.

Session costs persist to project config and restore on --resume, so cost display is accurate across session resumption.

Token estimation

The token estimation service (src/services/tokenEstimation.ts) provides three accuracy levels:

The rough estimation is file-type-aware: JSON uses 2 bytes/token (higher token density); everything else uses 4. Images and documents are a fixed 2000 tokens.

These estimates drive threshold decisions throughout the system — auto-compact triggers, context window budgets, tool result persistence.

Prompt cache economics

Prompt caching is not an optimization — it's the cost model. Claude Code achieves 92% overall prompt cache prefix reuse. The architecture enforces this:

Cache-preserving patterns

1. Tool registration order — built-in tools sorted alphabetically as a contiguous prefix, MCP tools as a sorted suffix. Adding/removing an MCP server invalidates only the suffix.
2. Fork agent cache sharing — sub-agents inherit the parent's exact system prompt and tool array, producing byte-identical API request prefixes. The child gets cache hits from the parent's cached prefix.
3. Micro-compaction with cache edits — removes old tool results via the API's cache_edits mechanism without invalidating the cached prefix.
4. One-shot agent optimization — Explore and Plan agents skip agentId/SendMessage/usage trailer, saving ~135 chars × 34M runs/week.

Cache-breaking risks

Scale impact

At Claude Code's scale (4% of all public GitHub commits), even small cache efficiency changes have massive cost implications. The autocompact death loop wasted ~250K API calls/day globally. A PR that dropped cache hit rate from 92.7% to 61% was immediately reverted.

Tool result storage economics

Large tool outputs are persisted to disk rather than kept in conversation context: - maxResultSizeChars = 30,000 — threshold for disk persistence - MAX_PERSISTED_SIZE = 64MB — absolute limit - Images resized to max 20MB

This prevents memory bloat during long sessions with hundreds of file reads, and keeps the conversation context budget for actual reasoning.

Context window management

The auto-compact system manages context budget through three tiers:

1. Microcompaction — continuous trimming of old tool results (zero API cost)
2. Session memory compaction — uses extracted session memory as summary (zero API cost)
3. Full compaction — LLM-generated structured summary (API cost, but uses cache-sharing fork)

Threshold: effectiveContextWindow - 13K buffer. For a 200K-context model: triggers at ~167K tokens.

Related entities

• cost-tracker — per-session cost accumulation and display
• token-estimation-service — three-tier token counting
• cache-economics — the deep dive on cache preservation
• auto-compact — context window management
• tool-system — cache-aware tool registration
• forked-agent-pattern — cache-sharing fork model