Welcome to Token Optimizer
Relevant source files
The following files were used as context for generating this wiki page:
- plugins/token-optimizer/skills/token-optimizer/SKILL.md
- plugins/token-optimizer/skills/token-optimizer/references/agent-prompts.md
- plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md
- plugins/token-optimizer/skills/token-coach/SKILL.md
- hermes/README.md
- plugins/token-optimizer/skills/token-coach/references/coach-patterns.md
Token Optimizer is a comprehensive performance and cost management suite designed for LLM-based autonomous agents, specifically targeting Claude Code, Codex, and Hermes runtimes. Its primary purpose is to identify and eliminate "ghost tokens"—unnecessary context window waste that causes sessions to feel sluggish, degrades output quality, and increases API costs.
The system operates through a multi-phase optimization pipeline that includes environmental auditing, automated implementation of fixes, and post-verification of savings. By managing configuration cleanup and autocompact behavior, it aims for 5-15% context recovery from basic cleanup and up to 25%+ recovery through advanced management strategies.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:1-10, hermes/README.md:1-10
System Architecture
Token Optimizer utilizes a tiered architecture to analyze and optimize the agent's environment. It employs a set of specialized subagents to perform parallel audits across different configuration layers.
The Optimization Pipeline
The core workflow is divided into specific phases, starting from environment detection to final verification.
The diagram shows the high-level flow from initial detection to the centralized trends database.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:90-185, hermes/README.md:126-140
Component Breakdown
| Component | Function | Runtime Targets |
|---|---|---|
measure.py | Central engine for tracking, scoring, and dashboarding. | All |
| Audit Agents | 6 parallel subagents (CLAUDE.md, MEMORY.md, Skills, MCP, Commands, Advanced). | Claude Code, Codex |
| Token Coach | Interactive advisor for architecture decisions and habit tracking. | Claude Code, Codex |
| Hermes Plugin | Native Python plugin for turn-based capture and context nudges. | NousResearch Hermes |
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:120-135, plugins/token-optimizer/skills/token-coach/SKILL.md:1-15, hermes/README.md:3-15
Core Features
Context Window Auditing
Token Optimizer dispatches specialized auditors to analyze various configuration files for token waste. This includes detecting duplicated content between CLAUDE.md and MEMORY.md, identifying oversized skill descriptions, and locating unused MCP servers.
This sequence demonstrates how individual audit results are combined into a single prioritized action plan.
Sources: plugins/token-optimizer/skills/token-optimizer/references/agent-prompts.md:1-300, plugins/token-optimizer/skills/token-optimizer/SKILL.md:120-140
Smart Compaction and Keep-Warm
To maintain session performance, the system provides:
- Smart Compaction: Uses
PreCompactandSessionStarthooks to preserve critical session context (decisions, error states) that would otherwise be lost during generic model compaction. - Keep-Warm: An opt-in feature for API-billed sessions that "pings" the prompt cache before it expires (typically a 1-hour window) to avoid expensive prefix rewrites.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:40-75, plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:165-175
Context Quality Scoring
Sessions are graded on a 0-100 scale based on active signals. High-quality sessions maintain a "Quality Zone" longer before performance degradation occurs.
| Signal | Description | Target |
|---|---|---|
| Context Fill | Percentage of model window occupied. | < 70% |
| Message Count | Risk increases as session length grows. | < 20 messages (S grade) |
| Output/Input Ratio | Measure of productivity vs context overhead. | High Ratio |
| Stale Reads | Detection of files read but subsequently modified. | Zero |
Sources: hermes/README.md:65-90, plugins/token-optimizer/skills/token-coach/references/coaching-scripts.md:130-160
Implementation Playbook
The system provides automated and manual pathways for applying optimizations identified during the audit phase.
CLAUDE.md Tiered Architecture
One of the most impactful optimizations is restructuring CLAUDE.md into a tiered model:
- Tier 1 (Always Loaded): Identity, critical rules, key paths (~300 lines).
- Tier 2 (On-Demand): Workflows and tool configs moved to specific skills.
- Tier 3 (Explicit Reference): Detailed standards and guides moved to external reference files.
Sources: plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:7-25
Model Routing Strategies
To reduce costs, Token Optimizer encourages routing tasks to the most efficient model tier.
The diagram outlines the suggested logic for assigning tasks to different model tiers to balance cost and capability.
Sources: plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:215-230
Operational Safety
Token Optimizer adheres to strict safety and privacy rules to ensure it does not break existing developer workflows:
- Backups: Mandatory backup of the
~/.claudeor~/.hermesenvironment before any modification. - No Deletions: Unused skills or rules are moved to a
_backups/or_archived/directory outside the active namespace rather than being deleted. - Read-Only Access: For runtimes like Hermes, the plugin accesses the state database in immutable, read-only mode.
- Local Execution: All analysis and measurement happen locally; no telemetry or data is sent to external services.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:200-215, hermes/README.md:110-120, plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:35-45
Conclusion
Token Optimizer serves as an essential tool for developers building complex, multi-agent systems. By providing real-time measurements and automated configuration tuning, it ensures that agents operate within their optimal performance zones while minimizing unnecessary API expenditures. Whether through the proactive "Context Nudges" in Hermes or the deep-dive audits in Claude Code, the system prioritizes context availability for actual problem-solving over configuration overhead.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:1-15, hermes/README.md:140-150