Token Optimizer Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Token Optimizer Skill is a comprehensive system designed to monitor, analyze, and optimize token usage within Claude Code environments. Its primary purpose is to maximize the utility of the context window by identifying and removing "token waste"—redundant or low-value data that consumes the context budget and degrades model performance. The skill provides a structured framework for auditing configurations, automating cleanup tasks, and implementing behavioral changes that extend the peak quality zone of long-running sessions.
Sources: skills/token-optimizer/references/token-flow-architecture.md:1, skills/token-optimizer/references/optimization-checklist.md:5-10
Architecture and Workflow
The system operates through a multi-phase orchestrated workflow using specialized subagents. It transitions from data gathering to synthesis and finally to execution/verification.
Orchestration Lifecycle
The workflow is divided into specific phases, coordinated through a session coordination folder (COORD_PATH).
This diagram illustrates the high-level data flow from initial audit to final verification.
Sources: skills/token-optimizer/references/agent-prompts.md:1-10, skills/token-optimizer/references/implementation-playbook.md:1-5
Core Audit Components
The audit phase employs several specialized auditors to inventory system overhead:
| Auditor | Model Target | Primary Focus |
|---|---|---|
| CLAUDE.md Auditor | Sonnet | Identifies content that belongs in skills or reference files; checks cache structure. |
| MEMORY.md Auditor | Sonnet | Detects duplication with CLAUDE.md and verbose operational history. |
| Skills/MCP Auditor | Sonnet | Checks for truncated descriptions (>1,536 chars) and deferred tool status. |
| Settings Auditor | Sonnet | Audits permissions.deny, hooks, and token-relevant environment variables. |
| Commands Auditor | Haiku | Inventories command overhead (~50 tokens per command). |
Sources: skills/token-optimizer/references/agent-prompts.md:15-180
Token Flow and Loading Sequence
Optimization is based on understanding the 13-level hierarchy Claude Code uses to load context for every message.
The loading sequence determines the baseline "irreducible floor" of tokens (approximately 15,000) versus variable user-controlled overhead.
Sources: skills/token-optimizer/references/token-flow-architecture.md:5-60, skills/token-optimizer/references/token-flow-architecture.md:315-330
Optimization Targets and Impact
High-impact targets are those loaded on every message, whereas skills and commands load only minimal frontmatter at startup.
- CLAUDE.md: Consolidating to ~300 lines can save 1,000–3,000+ tokens per message.
- Skills: Moving content from CLAUDE.md to a skill makes it 98% cheaper by only loading frontmatter (~100 tokens) until invoked.
- MCP Servers: Tool Search (active by default) defers full tool definitions, reducing overhead by ~85% compared to eager loading.
Sources: skills/token-optimizer/references/token-flow-architecture.md:80-140, skills/token-optimizer/references/optimization-checklist.md:20-50
Technical Implementation Strategies
Model Routing Logic
One of the highest-ROI behavioral changes is the implementation of task-specific model routing. This prevents the "Opus Addiction" anti-pattern where expensive models are used for simple data gathering.
Model routing ensures subagents use the most cost-effective model tier for their specific task.
Sources: skills/token-optimizer/references/optimization-checklist.md:120-170, skills/token-coach/references/coach-patterns.md:75-80
File Exclusion Rules
The system promotes using permissions.deny in settings.json to protect secrets and exclude noise like node_modules/ or build outputs. These rules are enforced locally and cost zero tokens in the prompt.
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./node_modules/**)",
"Read(./dist/**)"
]
}
}
Sources: skills/token-optimizer/references/implementation-playbook.md:65-90, skills/token-optimizer/references/optimization-checklist.md:60-75
Smart Compaction and Checkpoints
To mitigate information loss during the lossy auto-compaction process, the Token Optimizer implements Smart Compaction. This uses hooks to snapshot structured state (decisions, error-fix sequences, agent state) before compaction and re-inject it afterward.
- PreCompact Hook: Captures state to
~/.claude/token-optimizer/checkpoints/. - SessionStart Hook: Re-injects context to fill gaps left by the compaction summary.
- Compact Instructions: Guided sections in
CLAUDE.mdthat tell Claude what to preserve (e.g., test results, active decisions).
Sources: skills/token-optimizer/references/implementation-playbook.md:115-125, skills/token-optimizer/references/optimization-checklist.md:325-345
Usage and Environment Tuning
The skill audits specific environment variables in settings.json that affect token behavior:
| Variable | Default | Impact |
|---|---|---|
MAX_THINKING_TOKENS | 10,000 | Controls maximum tokens for chain-of-thought reasoning. |
ENABLE_TOOL_SEARCH | auto | Triggers deferred MCP tool loading (85% savings). |
BASH_MAX_OUTPUT_LENGTH | system | Limits bash stdout/stderr capture to prevent context flood. |
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | N/A | Removed by optimizer; causes premature lossy compaction. |
Sources: skills/token-optimizer/references/optimization-checklist.md:460-520, skills/token-optimizer/references/agent-prompts.md:235-255
Conclusion
The Token Optimizer Skill is an essential utility for power users of Claude Code, transforming token management from a manual guessing game into a data-driven engineering process. By combining aggressive configuration pruning (CLAUDE.md, Skill archival) with sophisticated behavioral patterns (Model Routing, Smart Compaction), the system ensures that the 1M+ token context window remains a high-quality space for complex reasoning rather than a repository for redundant configuration data.
Sources: skills/token-optimizer/references/token-flow-architecture.md:280-310, skills/token-optimizer/references/optimization-checklist.md:540-560