token-optimizer
Find the ghost tokens. Fix them. Survive compaction. Avoid context quality decay.
Install / Use
npx skills add alexgreensh/token-optimizerInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Skill content
View source on GitHubThe 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 Claude Code (CLI and VS Code), OpenCode, OpenClaw, Codex, Hermes, and GitHub Copilot. Windsurf and Cursor are next on the roadmap.
<p align="center"> <img src="skills/token-optimizer/assets/hero-terminal.svg" alt="Token Optimizer Quick Scan" width="800"> </p>Install
Claude Code (recommended):
/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizer
Then in Claude Code: /token-optimizer
<details> <summary><b>Other platforms and install methods</b></summary>Enable auto-update after installing. Claude Code ships third-party marketplaces with auto-update off by default.
/plugin→ Marketplaces tab → selectalexgreensh-token-optimizer→ Enable auto-update. One-time, 10 seconds.After install, run
/token-optimizeronce 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.
Codex:
codex plugin marketplace add alexgreensh/token-optimizer
Then in the Codex TUI: /plugins and install Token Optimizer. See docs/codex.md.
OpenCode: add token-optimizer-opencode to the plugin array in your opencode.json:
{ "$schema": "https://opencode.ai/config.json", "plugin": ["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
See hermes/README.md.
GitHub Copilot:
git clone --depth 1 https://github.com/alexgreensh/token-optimizer.git
cd token-optimizer
bash install.sh --copilot
See docs/copilot.md.
macOS/Linux script install (alternative to plugin):
tmp="$(mktemp -d)"
release_json="$(curl -fsSL https://api.github.com/repos/alexgreensh/token-optimizer/releases/latest)"
tag="$(python3 -c 'import json,sys; print(json.load(sys.stdin)["tag_name"])' <<<"$release_json")"
git clone --branch "$tag" --depth 1 https://github.com/alexgreensh/token-optimizer.git ~/.claude/token-optimizer
bash ~/.claude/token-optimizer/install.sh
rm -rf "$tmp"
Windows users: Use the plugin install only. Do not run install.sh on Windows. If you hit EBUSY errors, close all Claude Code and Git Bash windows, kill lingering git.exe processes, delete C:\Users\<you>\.claude\token-optimizer and C:\Users\<you>\.claude\plugins\marketplaces\alexgreensh-token-optimizer, then retry.
If install.sh fails with $'\r': command not found (a clone made before LF line endings were enforced converted the script to CRLF), strip the carriage returns once and re-run — the repo now ships a .gitattributes that prevents this on fresh clones:
sed -i 's/\r$//' ~/.claude/token-optimizer/install.sh
# already have the repo? re-normalize line endings in place:
git -C ~/.claude/token-optimizer add --renormalize . && git -C ~/.claude/token-optimizer checkout -- .
Token Optimizer is additive and reversible. Every runtime has a clean uninstall that removes only what we installed, leaving your own hooks, config, and session data intact. Full per-runtime steps live in docs/uninstall.md.
Quickest path (Claude Code plugin install):
/plugin uninstall token-optimizer@alexgreensh-token-optimizer
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.
How It's Different
Most token tools compress command output. That covers 15-25% of your context. The other 75% goes untouched.
Compression coverage. Headroom, RTK, and JFrog Boost compress bash and command output. Token Optimizer compresses eight surfaces of the output stack. Status: 🟢 supported, 🟡 partial, 🔴 not supported.
| Compression surface | Token Optimizer | Headroom | RTK | Boost | |---|---|---|---|---| | Bash / command output (git, tests, lint, build, logs) | 🟢 111 commands across 22 pattern families, credential-safe; 564 → 115 tokens on a pytest run | 🟢 SmartCrusher, CodeCompressor, Kompress-v2 | 🟢 100+ filters | 🟢 Command-aware filters | | Search / grep output | 🟢 Top hits plus a count; 500 lines → 20 | 🔴 | 🔴 | — | | Tabular / JSON output (jq, yq, csvtool, mlr) | 🟢 Value-preserving columnar | 🟢 SmartCrusher | 🔴 | — | | File re-reads, delta mode
Truncated for display — read the full file on GitHub.
Related Skills
career-ops
72.3kOpen-source AI job search: scan job portals, evaluate listings into a structured A-H report with a global 1-5 score, tailor your CV, track applications — runs locally in your AI coding CLI (Claude Code, Codex, OpenCode, Antigravity…)
ai-job-search
43.5kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
41.6kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
guizang-ppt-skill
26.7kAI-agent Skill for generating polished HTML slide decks: editorial magazine and Swiss layouts, image prompts, social covers, and a WebGL/low-power presentation runtime.
