Core Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
- plugins/token-optimizer/skills/token-optimizer/SKILL.md
- skills/token-optimizer/references/agent-prompts.md
- skills/token-optimizer/references/optimization-checklist.md
- plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md
- skills/token-coach/SKILL.md
- skills/token-coach/references/coach-patterns.md
The Token Optimizer is a multi-phase diagnostic and remediation system designed to identify and eliminate context window waste in Claude Code and Codex environments. Its primary purpose is to recover 5-15% of context through configuration cleanup and up to 25%+ via advanced autocompact management. The architecture relies on a central orchestration script, measure.py, which serves as the authoritative engine for detection, measurement, and lifecycle hook management.
The system is structured into two primary interaction models: Token-Optimizer for automated audits and fixes, and Token-Coach for interactive, data-driven architecture advice. Both modules leverage a tiered implementation strategy that separates static configuration from volatile session data to maximize prompt caching efficiency.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:1-12, skills/token-coach/SKILL.md:1-10
Multi-Phase Execution Flow
The core logic of the Token Optimizer is divided into six distinct phases (0 through 5), moving from environment validation to post-optimization verification.
The diagram above illustrates the sequential progression of the optimizer, highlighting the parallelized audit phase.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:130-175
Phase 0: Runtime Detection and Initialization
Before execution, the system performs an environment pre-gate to detect the runtime (Claude, Codex, OpenCode, or Copilot). This prevents unauthorized mutation of configuration paths. The system resolves the newest version of measure.py across multiple potential plugin paths to ensure version consistency.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:15-110
Phase 1 & 2: Distributed Auditing and Synthesis
The architecture employs six specialized agents (utilizing Claude Sonnet and Haiku models) to audit specific components of the environment. These agents write individual reports to a coordination folder (COORD_PATH). A Synthesis Agent, typically running on Claude Opus, then reads all reports to generate a prioritized optimization-plan.md.
Sources: skills/token-optimizer/references/agent-prompts.md:15-380
Tiered Configuration Architecture
The system enforces a tiered architecture for project configuration files (like CLAUDE.md) to optimize for prompt caching. Caching requires stable prefixes; therefore, volatile content must be separated from static instructions.
| Tier | Content Type | Loading Behavior | Target Size |
|---|---|---|---|
| Tier 1 | Identity, critical rules, key paths | Always loaded (Static) | ~300 lines / 4,500 tokens |
| Tier 2 | Workflows, tool configs, domain docs | Loaded on-demand (Skills) | N/A |
| Tier 3 | Full guides, templates, standards | Explicit file reference only | N/A |
Sources: plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:18-35, skills/token-optimizer/references/optimization-checklist.md:30-45
Lifecycle Hooks and Smart Compaction
A critical component of the architecture is the use of lifecycle hooks to manage context quality. These hooks are configured in settings.json and triggered by the environment during session transitions.
- PreCompact Hook: Snapshots structured session state (decisions, active file paths, error sequences) to disk before the environment performs a lossy compaction.
- SessionStart Hook: Re-injects the critical state captured by the PreCompact hook into the fresh context window.
- PostToolUse Hook: Triggers auto-formatters or quality checks after file edits to reduce output token waste.
- SessionEnd Hook: Executes
measure.py collectto record usage trends in a local SQLite database (trends.db).
Sources: plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:105-135, skills/token-optimizer/references/optimization-checklist.md:215-245
Model Routing Logic
The architecture incorporates a routing strategy to minimize API costs and rate limit consumption. It instructs the orchestrator to default subagents to the most efficient model based on task complexity.
The diagram shows the task-to-model mapping designed to reduce costs by up to 75% for multi-agent workflows.
Sources: skills/token-optimizer/references/optimization-checklist.md:130-170, plugins/token-optimizer/skills/token-optimizer/references/implementation-playbook.md:215-240
Data Persistence and Monitoring
Trend data and session history are stored locally to enable long-term optimization analysis. The measure.py trends command queries this database to provide insights into model distribution and quality scores.
- Trends Database:
~/.claude/_backups/token-optimizer/trends.db - Checkpoints:
~/.claude/token-optimizer/checkpoints/(stores last 50 checkpoints or 7 days of data). - Coordination Folder: A temporary directory created per session to hold audit reports and synthesis plans.
Sources: skills/token-coach/SKILL.md:40-75, skills/token-optimizer/references/optimization-checklist.md:240-255
Conclusion
The Token Optimizer architecture is a reactive system that combines environment-level lifecycle hooks with agentic auditing. By separating configuration into tiers and implementing smart routing and compaction, it maintains high context quality and minimizes token waste across long-running development sessions.
Sources: plugins/token-optimizer/skills/token-optimizer/SKILL.md:210-225