claude-code-token-optimization

# CLI Agent Token Optimization ## Core Mental Model Every session is not a blank slate—it's an **invoice**. Before your prompt even arrives, the system has already charged: - CLAUDE.md (always loaded) - Every active plugin Hook (always injected) - Every relevant Skill's SKILL.md (loaded on any "relevance" match) - Every connected MCP's tool schema (always transmitted) - Full conversation history (always re-read) - Cache-expired re-tokenization (after 5 min idle) **"Productive tokens" are what remains after overhead. You optimize overhead first, prompt second.** ## The 7 Traps (sorted by impact) ### Trap 1: CLAUDE.md Bloat CLAUDE.md loads every single turn. A 5000-word CLAUDE.md at 200 turns/week = 1M tokens just on rules. **Target:** Combined global + project CLAUDE.md ≤ 1200 English words (~1500 tokens). **Fix:** ```bash wc -w ~/.claude/CLAUDE.md 2>/dev/null # global wc -w .claude/CLAUDE.md 2>/dev/null # project-level ``` Refactoring rules: 1. Framework-specific rules → project-level CLAUDE.md only (not global) 2. Recurring complex patterns → extract as Skills (zero cost when not invoked) 3. Delete rules you can't remember the reason for 4. Rewrite explanatory sentences into 3-word imperatives. Claude needs commands, not reasons. Typical result: 4800 → 900 words, behavior unchanged, baseline cost drops 30%. ### Trap 2: Session History Exponential Re-reading Each new message re-tokenizes the entire history. Message #60 costs 60x message #1. **Fix:** 1. **Edit, don't append.** Arrow-up → edit → resend. Replaces the bad turn instead of stacking on top. 2. **Hard limit: 20 messages per session.** After that: ask the agent to summarize, open a new session, paste summary as first message. 3. **Use `/compact`, not `/clear`.** `/compact` summarizes and restarts (keeps essentials, drops fluff). `/clear` loses everything including useful context. Typical result: 60 messages → 15 messages, history cost drops ~40%. ### Trap 3: Plugin Hooks Silently Injecting Plugins with `UserPromptSubmit` hooks inject content before your prompt arrives. 4 plugins can silently add 6000+ tokens. `SessionStart` hooks add "I'm ready!" notifications (~1400 tokens from 9 plugins). **Fix:** ```bash # Check what's being injected cat ~/.claude/settings.json | jq '.hooks.UserPromptSubmit' 2>/dev/null cat ~/.claude/settings.json | jq '.hooks.SessionStart' 2>/dev/null # Audit rule: if you can't explain WHY it needs to trigger every time, disable it # /plugin disable <plugin-name> ``` Keep only `UserPromptSubmit` hooks you can justify (e.g., git branch info). Kill the rest. Typical result: 4 → 1 UserPromptSubmit hook, 9 → 2 SessionStart hooks. Each prompt saves ~5800 tokens. ### Trap 4: Prompt Cache Expiry (5 minutes) Prompt cache expires after 5 minutes of idle. Return after coffee → system prompt + CLAUDE.md + MCP schemas (~8000 tokens) all re-tokenize at full price instead of 10% cache-read price. **Fix:** - **Quick workaround:** Bind a hotkey to send a trivial "ping" before stepping away. Keeps cache alive. - **Proper fix:** Upgrade to 1-hour cache (if available via API tier). Cache writes cost 2x base price (one-time), reads cost 0.1x. Breaks even after ~10 cache recoveries per session—easily exceeded in a workday. Typical result: cache expiry cost drops ~80%. ### Trap 5: "Just in Case" Syndrome (Skills + MCP Overload) Unused Skills load on any fuzzy relevance match (~1500 tokens each). All connected MCPs send their full tool schema every request (~7000 tokens for 12 MCPs, but you only use 3). **Combined overhead: ~20,000 tokens per request, for nothing.** **Fix:** ```bash # 7-day audit: which Skills were actually invoked? grep -h "skill_invoked" ~/.claude/logs/*.log | sort | uniq -c | sort -rn # Skills not in output → disable all of them # Check connected MCPs # /mcp # see how many you have # /mcp disable <server> # disable unused in current session ``` Edit `~/.claude/settings.json` to remove rarely-used MCPs from auto-load. Enable on-demand. Typical result: 11 Skills → 4, 12 MCPs → 3. Saves ~15,000 tokens per request. ### Trap 6: Extended Thinking Global Switch Extended Thinking burns 3000+ thinking tokens on trivial tasks ("rename this variable"). Only valuable for architecture decisions, complex debugging. **Fix:** - **Default OFF.** Enable per-message when needed (`Alt+T` in Claude Code). - **Heuristic:** If the agent's first answer is unsatisfactory, retry with Extended Thinking ON. 80% of tasks don't need it. ### Trap 7: Letting Wrong Answers Finish Agent writes 400 lines. You see it's wrong at line 50. Letting it finish wastes output tokens (priced higher than input). ~$15/month wasted this way. **Fix:** - **`Cmd+.` (Mac) / `Ctrl+.` (Windows) — immediately stop generation.** Agent keeps what's written, you redirect from there. - **Train reflex:** Hit stop within 5 seconds of recognizing wrong direction. It won't "get better." - Claude Code bonus: double-tap `Esc` to open checkpoint rollback—revert to any prior state and try a different approach. ## Pre-baked Audit Script Run this in your project root: ```bash #!/bin/bash echo "=== 1. CLAUDE.md size ===" wc -w ~/.claude/CLAUDE.md 2>/dev/null wc -w .claude/CLAUDE.md 2>/dev/null echo "Target: combined < 1200 words" echo "=== 2. UserPromptSubmit injection ===" cat ~/.claude/settings.json 2>/dev/null | jq '.hooks.UserPromptSubmit' echo "Target: 1-2, fewer is better" echo "=== 3. SessionStart Hook ===" cat ~/.claude/settings.json 2>/dev/null | jq '.hooks.SessionStart' echo "Target: only essential ones" echo "=== 4. Installed Skills ===" ls ~/.claude/skills/ 2>/dev/null echo "Target: 3-5 matching daily work" echo "=== 5. Connected MCPs ===" cat ~/.claude/settings.json 2>/dev/null | jq '.mcpServers // {} | keys' echo "Target: 3 always-on, rest on-demand" ``` Run weekly until every line hits target. ## What DOESN'T Work (Common Myths) | Advice | Actual Impact | Why | |---|---|---| | "Use Haiku for simple tasks" | ~3% savings | Context bloat dominates; cheap model on bloated context costs more than expensive model on lean context | | "Always /clear between tasks" | Negative effect | Loses needed context, forces re-explanation. Better: one long session per project with lean CLAUDE.md + audited hooks | | "Disable ALL Skills" | Net loss | You end up rewriting 200-token instructions in every prompt. Keep 3-4 truly-used Skills | | "Avoid peak hours" | ~7% impact | Only affects quota throttling, doesn't fix overhead. The 7 levers above matter far more | ## Agent-Specific Notes ### OpenCode - Uses `.opencode/skills/` directory (similar SKILL.md loading pattern) - MCP configuration in `.opencode/settings.json` - No direct `/compact` equivalent — summarize manually and start new session ### Gemini CLI - No CLAUDE.md equivalent (uses system instructions differently) - Session history re-read issue still applies — keep sessions under 20 turns - No plugin hooks, but extensions may inject context — audit extensions ### Codex - **System instructions**: Keep system prompt files lean (<1200 words). Same bloat principle as CLAUDE.md — every turn reloads the full context. - **Session history**: Exponential re-read cost applies equally. Hard cap at ~20 messages, then summarize + restart. - **No /compact equivalent** — manually summarize progress and open new session. - **Extended Thinking equivalent**: Use reasoning/o1 models only when needed (architecture, complex debug). Don't default to them for simple edits — they burn massive thinking tokens on trivial tasks. - **Stop generation**: Codex supports interrupt (Ctrl+C). Use it the moment you spot wrong direction — don't wait for it to finish. - **Sandbox/tool overhead**: Each connected tool/sandbox adds schema overhead. Audit and disable unused tools. ## The Bottom Line 70% of "Claude got dumber" is overhead. 30% is the model itself. Fix all 7 traps → productive token ratio goes from ~30% to ~65%. Real-world feel: **2-3x more capacity from the same subscription.**