alexgreensh/token-optimizer

Token Optimizer – what it is

Token Optimizer is a stand‑alone, zero‑dependency Python/TypeScript tool that plugs into a number of AI‑coding assistants (Claude Code, OpenCode, OpenClaw, Codex, Hermes, GitHub Copilot, etc.). Its purpose is to reduce the number of tokens that the assistant consumes during a coding session and to keep the work you do alive across session compactions. It does this automatically after a one‑time installation and audit, then runs in the background without further user interaction.

Why it matters

AI coding assistants are billed by the token they process. Most existing “token‑saving” tools only compress raw command‑line output, which typically accounts for 15‑25 % of the context. The rest – bloated configuration files, stale memory, verbose model output, unnecessary model routing, and loss from automatic context compaction – remains untouched. Token Optimizer targets all eight of these waste surfaces, measures the savings in real dollars, and preserves the savings even when the assistant’s own compaction runs.

Core features (high‑level)

Feature	What it does	Benefit
Smart compaction	Takes a checkpoint before the assistant’s automatic compaction and restores the saved context afterward.	Savings survive compaction; no lost work.
Session continuity	Stores cross‑session hints, cold‑resume data, and a per‑session SQLite audit trail (15 tables).	You can pick up where you left off without re‑running expensive commands.
Active compression (9 toggles)	Compresses bash/command output, search results, tabular/JSON output, file diffs, skeletons of large files, large tool results, model‑output verbosity, and structural context (configs, skills, memory).	Cuts token waste from ~75 % of a typical session.
Quality scoring	Seven signal‑based grades (S‑F) that update live.	Lets you see if aggressive compression harms answer quality.
Live dashboard	A local HTML page (http://localhost:24842/token‑optimizer) that updates after each session, showing token breakdowns, dollar savings, cache TTL, and quality trends.	Immediate visibility of cost and performance.
Command‑level helpers	/token‑optimizer (full audit), /token‑coach (30‑day trend), quick (10‑second health check), route (model‑effort estimate), savings (dollar report), report (per‑component token breakdown), memory‑review, expand (retrieve archived output), resume‑lean, etc.	One‑line commands give actionable fixes without leaving the assistant.
Zero runtime dependencies & telemetry	Pure standard‑library code; nothing is sent off‑machine.	No extra packages to manage and no privacy concerns.
Cross‑platform integrations	Available as a Claude Code marketplace plugin, a Codex plugin, OpenCode/ OpenClaw plugins, a Hermes install script, and a manual install for Copilot.	Works wherever you use an AI coding assistant.

How you get it

1. Install – the recommended path is the Claude Code marketplace (/plugin marketplace add alexgreensh/token-optimizer then /plugin install token‑optimizer@alexgreensh‑token‑optimizer). Other platforms have analogous commands or a small install.sh script.
2. Run once – invoke /token‑optimizer to set up the hooks and perform an initial audit.
3. Leave it alone – the hooks fire automatically on every subsequent session, compressing output, checkpointing, scoring quality, and updating the dashboard.
4. Optional – use the various slash‑commands to dig deeper, view reports, or adjust configuration (TOKEN_OPTIMIZER_* env vars or TOML files).

Who might use it

• Developers who rely heavily on Claude Code, Copilot, or similar agents for code generation and want to lower their cloud bill.
• Teams that run long‑running sessions (e.g., CI‑style debugging) and need session continuity after the assistant’s automatic context compaction.
• Anyone concerned about privacy (zero telemetry) while still gaining detailed cost analytics.

Limitations & scope

• The tool only works with the supported runtimes listed above; it does not integrate with generic LLM APIs.
• Savings are measured locally; they assume the pricing tiers of the respective assistants (four tiers are listed in the dashboard).
• While the project ships a benchmark suite, the “fleet‑level cross‑agent analysis” claim is based on internal testing and not an external certification.

---

TL;DR – Token Optimizer is a real, open‑source plugin that automatically trims token waste across many AI coding assistants, keeps your work alive across compactions, and shows you concrete dollar savings on a live dashboard, all without extra dependencies or telemetry.