ooples /
token-optimizer-mcp
MCP server and Claude Code plugin that cuts agent token use and keeps a project graph
- 561 stars
- 23 stars since 3 Oct
- JavaScript
- Updated today
- Some experience
- Token & cost savings
AI coding agents waste context by re-reading unchanged files, dumping whole files to see a few lines, and running unbounded searches. They also forget what they worked out in earlier sessions. Token Optimizer targets all of these.
In Claude Code it installs as a plugin that denies large Read, Grep, Glob and similar calls and points the model to cached replacements. Re-reading a file returns only a diff. A local graph of files, symbols, tasks and findings fills in from normal tool traffic, and relevant notes are fed back when the agent touches a file.
The README says it optimizes the provider bill, which depends on prompt caching, rather than bytes removed. It ships benchmarks and admits one loss: on its codebase-exploration workload a competing design reduces slightly more (47.4% against 46.0%). A local dashboard attributes savings per client across 16 CLI clients, and telemetry is opt-in and off by default.
What it does
Denies costly tool calls
The plugin refuses large Read, Grep, Glob, Edit, Write and shell cat/head/grep -r calls. The refusal names a cached, diffed replacement.
Diff-only re-reads
Reading a file already read this session returns only what changed. The README calls this usually the biggest single saving.
Per-project knowledge graph
Nodes for files, symbols, tasks and findings are linked by edges such as supersedes and contradicts. Findings come from session evidence on disk or from the model writing them with wiki_write.
Rerunnable benchmarks
Scripts such as bench/compression/proof.mjs and session-replay.mjs regenerate the published figures, including a row where it loses to a competitor.
Per-agent savings dashboard
A local dashboard groups returned context and net savings by operation and client identity, across 16 supported CLI clients. The token_audit tool gives a ranked list of what costs most.
What you could build
- Cut the context an AI coding agent spends on repeated file reads in Claude Code.
- Keep findings, decisions and dead ends across sessions so the agent stops re-deriving them.
- Compare token savings between Codex, Claude Code and Gemini CLI in one local dashboard.
- Run the included benchmarks to check compression claims against your own setup.
- Run token_audit to get a ranked list of the biggest token costs per session.
Get started
In Claude Code, add the marketplace, install the plugin (not just the bare MCP server, since the plugin does the enforcing), and reload. Then run token_audit to see what to fix first. Other clients are covered in the README's installation section.
/plugin marketplace add ooples/token-optimizer-mcp/plugin install token-optimizer@token-optimizer/reload-pluginsCommands are copied from the project's README. Read it on GitHub for the full setup.
More in Token & cost savings
caveman
Makes coding agents answer tersely and shrinks the logs and output they read
rtk
A command-line proxy that shrinks shell output before your AI coding agent reads it
headroom
Shrinks tool outputs, logs, and files before your AI agent sends them to the model
codegraph
A local code knowledge graph that lets AI coding agents look up code in one call
freellmapi
One OpenAI-style API that routes across dozens of free LLM provider tiers
context-mode
Keeps bulky tool output out of your coding agent's context window
9router
Local proxy that routes AI coding tools to subscription, cheap, or free models
pxpipe
Local proxy that renders Claude Code's bulky context as images to cut input tokens
Switchyard
Routing library that picks which LLM handles each agent request
billion-context
A proxy that compresses long coding-agent chats so one session can run for weeks