token-optimization

Files (8)

• README.md
• SKILL.md
• cache-deep-dive.md · references/
• claude-md-templates.md · references/
• tools.md · references/
• validate_skill.py · scripts/
• functional-tests.md · tests/
• trigger-tests.md · tests/

SKILL.md (first lines)

# 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 default — use local file)*
- Very large codebase → keep 1M, but optimize practices below even more aggressively.

> **RAM analogy**: having 32GB RAM doesn't justify poor memory management. A constrained window forces better discipline.

### Context forking and isolated agents

Agents inherit parent context at spawn time. **The longer you wait, the heavier they start.**

Target behavior:

- Call each skill or agent in a **forked context** (`context: fork` in parameters)
- Agent works in its own window → at completion, returns *only the result*, not full history
- When agent is destroyed, main context hasn't moved

**Systematic use cases to isolate in subagent:**

From valorisa/Claude-Skills, MIT.

More from valorisa/Claude-Skills