alexgreensh/token-optimizer

Token Optimizer – What It Does

Token Optimizer is a Python‑based tool that plugs into a range of AI‑coding assistants (Claude Code, GitHub Copilot, Cursor, etc.) and automatically reduces the number of tokens those assistants waste during a coding session. Tokens are the units a language model counts when it reads your prompt and generates a response, and they translate directly into the cost you pay for the model’s API usage.

Core Features (run automatically)

Feature	What it does	Why it matters
Smart Compaction	Takes the output of commands, searches, JSON tables, etc., and compresses it before it is sent to the model.	Cuts 15‑25 % of raw output and the additional 75 % of “structural” waste the README calls out.
Session Continuity	Saves checkpoints before the AI’s automatic context compaction and restores them afterwards; keeps hints across sessions.	Prevents saved tokens from being lost when the model discards old context.
Active Compression (9 switches)	Delta diffs, skeleton extraction, bash‑output compression, lean‑output nudges, loop detection, and more – all enabled by default.	Reduces token count without changing the meaning of the data.
Quality Scoring	Computes a live grade (S‑F) from seven signals that reflect context health.	Gives you an at‑a‑glance view of whether the session is becoming noisy or inefficient.
SQLite Audit Trail	Stores a 15‑table local database with per‑component token usage, dollar savings, and timestamps.	Enables the /token‑coach 30‑day trend report and lets you review historic waste.
Progressive Disclosure	Large tool results are archived on disk; you can expand them on demand.	Keeps the prompt short while still letting you retrieve full output later.
Model Routing Nudges	Detects when a task would be cheaper on a lower‑tier model and suggests a switch.	Saves money by avoiding unnecessary use of expensive models.

On‑Demand Commands

• /token‑optimizer – full audit with guided fixes
• /token‑coach – 30‑day trend analysis
• quick – 10‑second health check
• route – tells you the cheapest model tier for the current task
• savings – dollar‑saving report
• report – token breakdown per component
• dashboard – opens the live web UI
• memory‑review – audits the MEMORY.md structural file
• expand – pulls an archived large output back into the prompt
• resume‑lean – re‑opens a cold session with saved context

Supported Platforms

The tool ships a plugin for Claude Code (the primary recommendation) and also works with Codex, OpenCode, OpenClaw, Hermes, GitHub Copilot, Pi Coding Agent, Cursor, Google Antigravity (beta), and Grok Build (beta). Installation varies per platform but generally involves a one‑time plugin add and a single /token‑optimizer command to bootstrap the hooks.

How It Differs From Other Token Tools

Aspect	Token Optimizer	Headroom / RTK / Boost
Coverage	Compresses bash output, search results, tabular/JSON, file diffs, skeletons, large tool results, model verbosity, and structural config files – eight surfaces total.	Typically only compresses command output (15‑25 % of context).
Persistence	Checkpoints before automatic compaction and restores after, so savings survive later compaction passes.	No persistence; savings disappear when the model discards context.
Metrics	Before/after token counts, dollar savings, quality grades, 30‑day trend graphs.	Mostly token‑count reports; no cost or quality scoring.
Dependencies / Telemetry	Zero external dependencies, no telemetry, runs locally.	May require a background service or send data to a vendor.

Installation Quick‑Start (Claude Code)

/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizer
/token-optimizer   # runs the one‑time audit and sets up hooks

After that the optimizer works silently in the background; you only need to invoke the slash commands when you want a report or to adjust settings.

Who Might Use It?

• Individual developers who rely on AI coding assistants and want to keep their API bill low.
• Teams that run many AI‑assisted sessions and need a systematic way to audit token waste.
• Ops/DevOps engineers who want a zero‑dependency, privacy‑preserving solution (no telemetry, local SQLite DB).

---

All information above is taken directly from the project's README; no additional features have been inferred.