token-optimization

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: token-optimization
description: Optimize token consumption in Claude Code through cache management, context forking, model selection, and input filtering. Use when user mentions high token costs, context window bloat, slow sessions, cache invalidation, verbose agent output, heavy MCP load, or any context management issues. Covers four critical axes - cache misses, context bloating, wrong model/effort level, and verbose input formats. Triggers on "tokens", "cost", "expensive", "context", "cache", "slow session", "optimize", or symptoms of token waste even without explicit mention.
metadata:
  author: valorisa
  version: 1.0.0
  category: workflow-automation
  requires: [bash, git]
---

# Token Optimization — Claude Code

## Overview

Token overconsumption in Claude Code stems from **four main sources**:

1. **Cache miss** — uncached or invalidated requests
2. **Context bloating** — unnecessarily growing context window
3. **Wrong model / wrong effort** — reasoning overuse
4. **Verbose input format** — overly verbose data injected into context

---

## Phase 1: Initial Session Audit

Before any work, run these two commands:

```bash
/context   # Shows loaded MCPs and tokens already consumed
/plugin    # Lists active plugins
```

**Systematic actions:**

- Disable all MCPs not needed for current project
- Disable all unused plugins
- One project ≠ one global config → customize per project

> Real example: empty session with Canva + Gmail + Google Calendar MCPs loaded = **23,000 tokens consumed before first keystroke**.

**Red flags to check:**

- More than 3 MCPs loaded
- Plugins unrelated to current work
- Base token count >10,000 on empty session

---

## Phase 2: Cache Management

### Principle

Claude Code caches: system instructions (CLAUDE.md), tool/MCP list, and message history. Any **modification during session** invalidates this cache, causing complete re-billing of affected tokens.

### Imperative rules

- **Never add a tool, MCP, or model mid-session.**
  Configure everything *before* starting, or in a dedicated setup session.
- If a critical addition is required mid-session (heavy skill, MCP, critical command):
  1. Compact the session (`/compact`)
  2. Start new session with compacted summary as starting point
- Treat cache like **HTTP cache**: changing a header invalidates everything downstream.

### Cache invalidation hierarchy

```
┌─────────────────────────────────────────────┐
│ BASE SYSTEM INSTRUCTIONS (CLAUDE.md + tools)│  ← Invalidated if tool added
├─────────────────────────────────────────────┤
│ SESSION STATE (project files, memory)       │  ← Invalidated if file changes
├─────────────────────────────────────────────┤
│ MESSAGE HISTORY                             │  ← Invalidated if message edited
│  msg 1 → msg 2 → msg 3 → ...                │     (invalidates everything after)
└─────────────────────────────────────────────┘
```

**What invalidates cache:**

| Action | Layer invalidated | Impact |
|---|---|---|
| Add MCP mid-session | Base instructions | Very high |
| Add tool (tool calling) | Base instructions | Very high |
| Modify CLAUDE.md | Base instructions | Very high |
| Edit message in middle of history | Message history (from that point) | Moderate |
| Load new file into context | Session state | Moderate |

**Optimal session strategy:**

```
1. Full configuration (MCP, tools, CLAUDE.md) → BEFORE starting
2. Work session → NEVER modify configuration
3. If modification needed → /compact → new session
4. Agents → context fork → isolated work → result only
```

For technical details on cache issues, see `references/cache-deep-dive.md`.

---

## Phase 3: Context Window Optimization

### Reduce default context window

The 1M token window is tempting but dangerous: it encourages bad habits and overloads child agents.

**Conditional recommendation:**

- Small/medium codebase → limit to ~200,000 tokens in `settings.json`:

  ```json
  { "contextWindow": 200000 }
  ```

  *(not committed by defa