Common token consumption problems and solutions, based on 800+ hours of autonomous operation.

Cause: Large context window + cache misses. When prompt cache breaks, every turn pays full price.

Quick fixes:

1. Check your CLAUDE.md length: wc -l .claude/CLAUDE.md — over 100 lines = significant overhead every turn
2. Run /cost to see cache hit ratio — below 80% means cache is breaking frequently
3. Don't edit CLAUDE.md or settings.json mid-session — this invalidates cache

Deeper fix: Restructure CLAUDE.md to under 35 lines. Move details to Skills files. See the Token Optimization Guide for the full approach.

→ Token Checkup — free 5-question diagnostic

Known issues (April 2026):

• v2.1.100+: cache_creation inflated by ~20K tokens (#46917, 97 reactions)
• v2.1.104: System prompt cache overhead increased 94% — 49.7K→96.5K tokens on cold cache (#47528)
• v2.1.105: Cold start overhead increased from 4%→11% (#47659)

Check your version: claude --version

→ Version Health Check — see which known issues affect your version

Cause: After /compact, Claude forgets file contents and re-reads them. Large files (100KB+) consume thousands of tokens per read.

Fix with a hook:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "if [ \"$TOOL_INPUT\" ]; then SIZE=$(stat -c%s \"$TOOL_INPUT\" 2>/dev/null || echo 0); [ \"$SIZE\" -gt 100000 ] && echo 'WARN: File is '$(( SIZE / 1024 ))'KB. Consider using offset/limit.' >&2; fi; exit 0"
      }]
    }]
  }
}

This warns (without blocking) when Claude tries to read a file larger than 100KB.

→ Hook Selector — find the right hooks for your workflow

Cause: Parallel subagents editing the same file get "File modified since read" errors and retry endlessly (#46968).

Prevention: Limit subagent spawning with a budget guard hook. Give each subagent a non-overlapping file scope.

Run /cost in Claude Code. Key numbers to check:

• Cache read ratio: Should be 80%+ in a healthy session
• Total session tokens: Compare across sessions to find anomalies
• Tool call count: High numbers suggest loops or excessive reads

→ Cache Health Checker — paste your /cost output for instant diagnosis

The Token Book (¥2,500 / ~$17) covers all of the above in depth:

• 10 chapters, 44,000 characters
• 9 copy-paste hook templates
• 800 hours of real measurement data
• CLAUDE.md optimization (100→35 lines, 40% token reduction)
• Troubleshooting flowcharts for cache crashes and token spikes

Free Token Checkup →