token-optimizer

The 30-Second Version

Token Optimizer cuts the tokens your AI coding assistant wastes, keeps your work alive across sessions and compactions, and shows you where every dollar went on a live dashboard. Most of it runs automatically. You install it, run the audit once, and the hooks do the rest.

Why not just use Headroom or RTK? They compress command output, which covers 15-25% of your context. Token Optimizer covers that plus the other 75%: bloated configs, unused skills, stale memory, compaction loss, model misrouting, behavioral waste. Every saving is cache-safe and measured. The dashboard updates after every session, automatically.

Works on the AI coding tools below, with a Devin output-filter beta (manual skill, or install.sh --devin --auto for automatic compression):

What You Get

Runs automatically, every session, you do nothing:

• 🔄 Smart Compaction: checkpoints before auto-compact, restores after
• 🗄️ Session Continuity: cross-session hints, cold-resume, checkpoint scoring
• 📦 Active Compression: 9 features, all on by default (delta diffs, skeletons, bash/search compression, lean-output nudges, quality nudges, loop detection, activity mode, decision extraction)
• 📊 Quality Scoring: 7 signals, real-time, letter grades S–F
• 🗃️ Session Database: SQLite, 15 tables, full audit trail, zero network
• 🔍 Progressive Disclosure: large outputs archived, expand on demand
• 🧠 Context Intel Digest: post-compaction re-orientation without re-reads
• 🔀 Model Routing Nudges: steers to the right tier for the task

When you ask for it:

• 🩺 /token-optimizer: full audit with guided fixes
• 📈 /token-coach: 30-day trend analysis with specific fixes
• ⚡ quick: 10-second health check
• 🎯 route: the model and effort this task actually needs, before you spend
• 🔧 doctor: installation check
• 💰 savings: dollar savings report
• 📋 report: per-component token breakdown
• 🌐 dashboard: open the full dashboard
• 📝 memory-review: MEMORY.md structural audit
• 📂 expand: retrieve archived tool result
• 🔙 resume-lean: reopen a cold session

Install, run /token-optimizer once, everything else runs automatically.

A Status Bar Inside the Claude Desktop App

Claude Code now lets a plugin add its own piece of interface, called a mod. Token Optimizer uses one to put your session's health right above the prompt: a quality grade, how full the context is, how long the cache stays warm, and both usage limits. One plain sentence tells you what needs attention, and one button fixes it. Clawd, the small orange mascot, acts out what the session is doing, so you can tell at a glance whether Claude is reading, editing, waiting for your OK, or done.

It comes with the plugin, nothing extra to install. Everything the bar does.

Install

Claude Code (recommended):

/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizer

Then in Claude Code: /token-optimizer

Enable auto-update after installing. Claude Code ships third-party marketplaces with auto-update off by default. /plugin → Marketplaces tab → select alexgreensh-token-optimizer → Enable auto-update. One-time, 10 seconds.

After install, run /token-optimizer once to set up hooks. From there, everything runs automatically: compression, checkpoints, quality scoring, dashboard updates. You don't need to run any command again unless you want an audit.

Claude Code cloud sessions (claude.ai/code). Cloud sessions load no plugins, not yours and not ones a repo enables, so the commands above don't reach them. Paste one setup script into your cloud environment instead and every session in it, any repo, runs the real Token Optimizer:

1. Run python3 measure.py cloud-setup-script (or ask Claude for "the Token Optimizer cloud setup script").
2. Paste the output into claude.ai/code → your environment → Setup script.

The script fetches the @alexgreensh/token-optimizer npm package (the plugin itself, same version), checks its sha512 before running anything, and wires the same hooks as hooks/hooks.json into the VM. Nothing is committed to your repos, and it never fails your setup. State lives in the VM, so each cloud session starts fresh. Details

Codex:

codex plugin marketplace add alexgreensh/token-optimizer

Then in the Codex TUI: /plugins and install Token Optimizer. See docs/codex.md.

OpenCode V2: add token-optimizer-opencode to the plugins array in your opencode.json (V1 1.18.29+ uses plugin):

{ "$schema": "https://opencode.ai/config.json", "plugins": ["token-optimizer-opencode"] }

See opencode/README.md.

OpenClaw:

openclaw plugins install github:alexgreensh/token-optimizer

See openclaw/README.md.

Hermes:

git clone https://github.com/alexgreensh/token-optimizer.git
token-optimizer/install.sh --hermes

Terminal output compression, cheaper re-reads, loop warnings, checkpoints that survive compaction, prior-session hints, and the dashboard, through Hermes's own plugin hooks. See hermes/README.md.

Pi Coding Agent:

pi install git:github.com/alexgreensh/token-optimizer

Then run /token-optimizer enable to opt in. Native model costs are reported on the active branch; local tool archives and continuity markers require separate opt-in. See pi/README.md for commands, privacy, update, uninstall, and limits.

GitHub Copilot:

git clone --depth 1 https://github.com/alexgreensh/token-optimizer.git
cd token-optimizer
bash install.sh --copilot

See docs/copilot.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗