If you use Claude Code and keep hitting your five-hour or weekly limit, a lot of that usage may go to setup you forgot about: long CLAUDE.md files, unused skills and MCP servers. Token Optimizer is an open plugin that audits this and suggests fixes. This guide shows how to install it, the message to paste, and the free built-in checks you can run first.
What you need
Claude Code with a Claude plan (Pro, Max, Team or Enterprise) or API billing. Token Optimizer is built for Claude Code, not for the regular Claude chat app.
Token Optimizer by Alex Greenshpun: github.com/alexgreensh/token-optimizer. Free for personal use. It has about 2.6k GitHub stars.
Python 3.9 or newer. The README lists it with zero dependencies and no telemetry.
For the status bar in the Claude desktop app: Claude Code 2.1.287 or newer.
Step by step
Check your usage with built-in commands first. These are free and already in Claude Code:
/usage: shows your plan usage limits and, on Pro, Max, Team or Enterprise, a breakdown of what counts against them./context: shows your current context as a coloured grid, with suggestions for heavy tools and memory bloat./skills: lists your skills. Presstto sort them by token count./mcp: lets you disable MCP servers you don't use./memory: opens your CLAUDE.md files so you can trim them.
Install Token Optimizer. Inside Claude Code, run these two commands:
/plugin marketplace add alexgreensh/token-optimizer
/plugin install token-optimizer@alexgreensh-token-optimizerThe README also recommends turning on auto-update: `/plugin`, then the Marketplaces tab, select `alexgreensh-token-optimizer`, then Enable auto-update.
Run the first audit. This also sets up its background hooks:
/token-optimizerOr paste this message into Claude Code and let it walk you through the setup:
Please help me set up Token Optimizer from
https://github.com/alexgreensh/token-optimizer
1. Install it with the plugin commands from its README.
2. Run /token-optimizer and show me the audit.
3. List the 5 biggest sources of wasted tokens in my setup
(CLAUDE.md, skills, MCP servers, memory), biggest first.
4. For each one, explain the fix in one plain sentence and
ask me before you change any file.Look at the last 30 days. Run the coach for trends and prioritised fixes:
/token-coachIt reads 30 days of your session data and flags things like unused skills, MCP servers that load every time, and CLAUDE.md patterns that break your cache.
Use the status bar if you're on the Claude desktop app. After install, a bar appears above your prompt with five marks: quality grade, context fill, cache countdown, your five-hour limit and your weekly limit. It shows the most urgent issue in one sentence with at most one button to act on it, such as Clean up or Start fresh.
Start fresh when quality drops. Token Optimizer scores your session from S to F and warns you when context quality drops. When that happens, use
/compactto summarise, or/clearto start a new conversation.
Good to know
Claude Code only (plus other coding tools). It also supports Codex, Cursor, GitHub Copilot, OpenCode and others, but not the normal Claude chat website or app.
Savings are the maker's own numbers. In one month of his own use, the README reports about 28% of tokens never sent to the model. Part of that figure is measured and part is estimated. Your result will depend on your setup.
Licence. PolyForm Noncommercial 1.0.0. Personal use is free. Small businesses (fewer than 5 people and under $20k a month in revenue) get a free written permission. Larger companies need a commercial licence.
The status bar depends on Anthropic's mods feature. The README says Anthropic can switch mods off remotely. If that happens, the bar just doesn't appear. VS Code is not supported for the bar.
Some features are lossy. The opt-in Bash compression shortens command output. Review what it removes if you rely on full logs.
Third-party code. This is not an Anthropic product. Read the README before you install any plugin.
Sources
Found this useful? Follow @kevinsingh.me on Instagram for a new AI tool every day, and subscribe so you don't miss the next one.