Token Optimization — Claude Code

Overview

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

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

• 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.

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

Phase 2: Cache Management

Principle

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)
└─────────────────────────────────────────────┘

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

references/cache-deep-dive.md

Phase 3: Context Window Optimization

Reduce default context window

• 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

• 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

explore

For any web search, systematically delegate to isolated subagent.
Return only extracted relevant information, not full history.

Compaction and Rewind

• Automatic compaction: triggers when agent reaches ~80% of window. Desirable for agents, not for main session.
• Rewind (double

  Esc

  ): allows returning to previous conversation and deleting unnecessary context branch. Use immediately when going in wrong direction.

Phase 4: Model & Reasoning Effort Selection

Reasoning effort

think

Rule: if the answer is clear in your mind, use

medium

. Ask Claude to think with you, not for you.

Model choice

• Claude Code subscription → use native Anthropic models (Sonnet / Opus). No proxy.
  • Opus: prefer for complex tasks despite latency
  • Sonnet: fast tasks, common code generation
• Proxy to other LLMs (GLM, Kimi...): only relevant if using SDK/API directly, not in standard Claude Code. Proxies are unstable and unoptimized.

## Reasoning effort
- Simple task / known command → minimal effort, no `think`
- Design / architecture task → medium effort
- Complex unsolved problem → high effort only on explicit request
Never over-reason a simple task.

Phase 5: Input Format Optimization

Browser automation: DOM over screenshots

• Operates directly on DOM (invisible, no screenshots)
• Installation: open new Claude Code instance →

  Install [stagehand URL]

• Result: 10× faster, drastically reduced tokens

Filter verbose CLI output

git status

git diff

• Filters command output before context window injection
• Example:

  git status

  goes from ~50 lines to ~5 essential lines → ~80% savings on this command
• Global installation:
  bash

  # Run in Claude Code
  npx rtk init --global

Concise responses: Caveman Skill / CLAUDE.md

## Response style
Ultra-concise responses. Remove articles, politeness phrases, reformulations.
Get to the point. Format: short bullet points. No intro, no conclusion.

references/claude-md-templates.md

Specify file paths explicitly

# ❌ Costly: Claude will list, explore, read
"Update project memory"

# ✅ Optimal: explicit paths in command
"Update ./docs/memory.md and ./CLAUDE.md with following items: ..."

## Memory/Learning commands
`/learn` command: updates ONLY the following files:
- ./docs/project-memory.md
- ./CLAUDE.md (section "Project Context")
Do not scan other files unless explicitly instructed.

Phase 6: Validation & Monitoring

Check context consumption

/context    # Check current token count

• Base session <5,000 tokens (with necessary MCPs only)
• After 10 interactions: <30,000 tokens
• No agents exceeding 50,000 tokens for isolated tasks

Team monitoring

• Local dashboard tool (created by reference article author): displays sessions, called models, tokens per session
• More useful for managers/leads than solo developers
• See references below for link

Troubleshooting

High token count despite optimizations

1. Run

   /context

   → identify which MCPs are loaded
2. Check

   settings.json

   → verify contextWindow setting
3. Review recent commands → identify verbose outputs
4. Check agent spawns → verify context forking

• Disable unused MCPs
• Add RTK filtering for git commands
• Move to subagents for research tasks
• Reduce contextWindow if codebase allows

Cache invalidation happening frequently

1. Check if skills are being loaded mid-session
2. Verify CLAUDE.md isn't changing
3. Look for tool additions in session

• Preload all needed skills at session start
• Lock CLAUDE.md configuration
• Use dedicated setup session for config changes

Agents consuming too many tokens

1. Check if agents inherit bloated parent context
2. Verify agents aren't loading unnecessary MCPs
3. Look for verbose tool outputs in agent history

• Spawn agents earlier (lighter parent context)
• Use

  context: fork

  parameter
• Return only results, not full agent history

Examples

Example 1: Project setup with token optimization

1. Create minimal CLAUDE.md with concise response directives
2. Configure contextWindow based on codebase size
3. Enable only essential MCPs for project type
4. Add RTK filtering for git commands
5. Define subagent delegation rules
6. Verify base session <5,000 tokens

Example 2: Diagnosing high token consumption

1. Run

   /context

   to audit current state
2. Check loaded MCPs and plugins
3. Review recent command outputs for verbosity
4. Identify cache invalidation patterns
5. Generate optimization recommendations
6. Implement fixes prioritized by impact

Example 3: Web research task

1. Spawn isolated subagent with context fork
2. Subagent performs web searches
3. Subagent extracts key findings only
4. Return summary to main context (not full search history)
5. Main context receives ~500 tokens instead of ~5,000

References

• references/cache-deep-dive.md

  — Cache behavior and invalidation patterns

• references/claude-md-templates.md

  — Ready-to-use CLAUDE.md configuration blocks

• references/tools.md

  — External tools (Stagehand, RTK) setup guides

• Anthropic Prompt Caching Documentation
• Stagehand Browser Automation
• RTK CLI Output Filter

Quality Checklist

• Base session <5,000 tokens
• Only essential MCPs loaded
• CLAUDE.md includes concise response directives
• Context forking configured for research tasks
• RTK or equivalent filtering installed for verbose commands
• contextWindow set appropriately for codebase size
• Team members trained on cache invalidation rules (if applicable)