Token Optimizer is positioned as "cutting the tokens you waste while preserving the work you would lose." According to the official description, it is aimed at AI coding assistant workflows, runs automatically in the background, lets users work as usual, and runs an audit when they need the full picture. Its slogan is: find ghost tokens, fix them, survive compression, and avoid context quality decay.
In terms of purpose, the official description emphasizes that it does more than compress command output. It believes command output accounts for only about 15%-25% of context, while the remaining roughly 75% is not covered, including bloated configuration, unused skills, stale memory, compression loss, model misrouting, and behavioral waste. The official description says every saving is cache-safe and measurable, and the dashboard updates automatically after each session.
The main capabilities fall into two categories: "automatic operation" and "on-demand operation." Automatic operation includes: smart compression (checkpoint before automatic compression, restore after compression), session continuity (cross-session prompts, cold recovery, checkpoint scoring), proactive compression (9 features enabled by default: incremental diff, skeleton, bash/search compression, lean output prompts, quality prompts, loop detection, activity mode, decision extraction), quality scoring (7 signals, real-time, S-F letter grades), session database (SQLite, 15 tables, full audit trail, zero network), progressive disclosure (large output archiving, on-demand expansion), context intelligence summaries (reorientation after compression without rereading), and model routing prompts (guide to the appropriate tier). On-demand commands include: /token-optimizer full audit and guided fixes, /token-coach 30-day trend analysis, quick 10-second health check, route gives the model and effort needed for a task before spending, doctor installation check, savings dollar savings report, report token breakdown by component, dashboard opens the full dashboard, memory-review MEMORY.md structure audit, expand retrieves archived tool results, resume-lean reopens a cold session.
In terms of usage, the official description provides multiple installation paths. For Claude Code, installation through the plugin marketplace is recommended, then run /token-optimizer in Claude Code; after installation, it is recommended to enable automatic updates (/plugin → Marketplaces tab → select alexgreensh-token-optimizer → enable automatic updates, one-time about 10 seconds). After installation, run /token-optimizer once to set up hooks; after that, compression, checkpoints, quality scoring, and dashboard updates all run automatically. Claude Code cloud sessions (claude.ai/code) run in a fresh container and do not read local plugins, so you need to enable it for your claude.ai account, or commit the configuration to the repository's .claude/settings.json; cloud sessions have an empty state directory each time, so the dashboard and audit history only cover that session. Codex is installed in the TUI using /plugins (see docs/codex.md). OpenCode V2 adds token-optimizer-opencode to the plugins array in opencode.json (V1 1.18.29+ uses plugin). For OpenClaw and Hermes, see their respective READMEs. After installing Pi Coding Agent, run /token-optimizer enable to opt in; local model costs are reported on the active branch, and local tool archiving and continuity markers require separate opt-in; for commands, privacy, updates, uninstallation, and limitations, see pi/README.md. For GitHub Copilot, Cursor, Google Antigravity, and Grok Build (beta, contract only), see docs/copilot.md, docs/cursor.md, docs/antigravity.md, and docs/grok.md respectively. There is also a macOS/Linux script installation as an alternative to the plugin; Windows users can only use the plugin installation and should not run install.sh; if you encounter an EBUSY error, close all Claude Code and Git Bash windows, end any remaining git.exe processes, delete C:\Users<you>.claude\token-optimizer and C:\Users<you>.claude\plugins\marketplaces\alexgreensh-token-optimizer, and then retry. If install.sh reports $'\r': command not found (caused by cloning before LF line endings were enforced, resulting in CRLF), remove the carriage returns and run it again.
The Claude Code plugin also provides a status bar (mod) within the Claude Desktop app: it shows the quality grade, context fill level, cache retention duration, and two usage limits, a one-sentence hint about what needs attention, and a single button to fix it; the mascot Clawd indicates session status. This status bar ships with the plugin and requires no additional installation.
How it differs from other tools: the official descriptions of Headroom, RTK, JFrog Boost, and others mainly compress bash and command output, whereas Token Optimizer covers eight facets of the output stack and extends beyond compression: structural waste (bloated configuration, unused skills, stale memory), runtime waste (verbose output, repeated reads), and behavioral waste (model misrouting, cache expiration, retry loops); savings survive compression; it can measure whether it helped (before-and-after token differences, dollar savings across four pricing tiers, quality scoring); zero baseline overhead (external processes, no resident context instructions, no MCP servers, no dependencies, no telemetry).
The 9 proactive compression features are enabled by default, automatic, and can be toggled from the dashboard or CLI. The mechanism is: PreToolUse hooks intercept Read and Bash calls before they enter context; if a file has already been read, only the diff is returned; if a code file is read repeatedly, the full text is replaced with a structural skeleton; if it is a CLI command, the output is compressed; PostToolUse hooks archive the complete original content to disk and record compression events in SQLite, and the content is retrievable. Features include: incremental reads (re-reading after edits returns only the diff; officially, 65%+ of Reads in real sessions are re-reads, and a 2000-token file re-read becomes a 50-token diff; can be disabled with TOKEN_OPTIMIZER_READ_CACHE_DELTA=0); shadow reads (repeated reads of code files are replaced with a structural summary; a 720KB Python file's 180,000 tokens become a 250-token skeleton; can be disabled with TOKEN_OPTIMIZER_READ_CACHE_MODE=shadow); first-read skeleton (as of v5.12, the target file's first read is always provided in full; savings come from the peripheral skeleton injected alongside it (one-hop relationships, PageRank ranking), and it applies only to code; first reads of prose such as Markdown are not skeletonized; can be disabled with TOKEN_OPTIMIZER_FIRST_READ_ACTIVE=0 stops serving, TOKEN_OPTIMIZER_FIRST_READ_SHADOW=0 fully disables); Bash output compression (rewrites common CLI command returns into compressed summaries, covering lint, log tails, tree, docker pull, long listings, build output, and test runners; a 564-token pytest output becomes 115 tokens, can be disabled with TOKEN_OPTIMIZER_BASH_COMPRESS=0); custom command filters (TOML, located at <runtime-home>/token-optimizer/command-filters.toml, path can be overridden with TOKEN_OPTIMIZER_COMMAND_FILTERS; the loader rejects shell interpreters, privilege-escalation wrappers, destructive write subcommands, or add entries containing shell metacharacters, and the classification exclusions cannot be overridden by user configuration); search result compression (when grep, rg, or web search returns long lists, compresses to top hits plus a count; a 500-line grep becomes 20 lines plus a summary, sharing the same switch as bash compression); concise output prompting (when context fill exceeds 25%, prompts the model to reason deeply but keep visible output concise, conditioned only on fill, with savings estimated at 10–15% rather than measured); and so on.
On the dashboard side: a single HTML page, automatically regenerated after each session by the SessionEnd hook, with no manual trigger needed. A bookmarkable URL http://localhost:24842/token-optimizer requires first running python3 skills/token-optimizer/scripts/measure.py setup-daemon to start the local server before it is available; before that, open the file path printed on the Dashboard: line by measure.py dashboard. The dashboard includes per-turn token breakdown, four-tier pricing costs, cache analysis (TTL mix and hit rate), quality scores overlaid on each session, subagent cost breakdown, and a savings tracker (with metered and estimated tiers kept separate).
On the benefits data side, the official example is based on the author's most recent 30 days, with all six levers enabled, across 1,698 sessions (snapshot 2026-09-14): the metered portion "recorded operations" is about $126, with 2,733 events carrying before-and-after token counts; the estimated portion "avoided repeated reads" is about $1,124; other estimates are about $146. The total is about $1,396 in API-equivalent value, with 59.6M tokens never sent to the model, about 28% of the workload (150.8M spent, versus about 210.4M without it). The official guidance emphasizes that tokens are the primary number, dollars depend on the model used, metered and estimated are never merged into a single number, and the user's own numbers are calculated by the dashboard based on their own sessions.
Limitations and gaps: the above benefits are an official example based on the author's sessions and do not represent the user's own results. Some platforms are marked as beta (such as Devin output filtering and Grok Build contract-only), and some integrations are linked in the documentation but not expanded in the main text. Regarding pricing, payment models, platform availability, and specific usage steps, the materials do not yet provide complete information, and the corresponding documentation for each integration should be consulted.
