
Token Optimizer MCP
Cut what your AI coding agent costs without cutting what it gets done.
Hooks, a proxy, and an MCP server for Claude Code, Codex, Copilot, Gemini and 12 more clients.
Quick start ·
How it works ·
Benchmarks ·
All 16 clients ·
Reference ·
Changelog
On SWE-bench Verified, Claude Code with the plugin in its default mode solved the
same tasks as Claude Code without it, at 0.71× the cost (7 of 7 resolved in
both arms; across nine runs, 84 tasks resolved without the plugin and 83 with
it). It gets there by stopping the waste agents make on their own: re-reading
files that have not changed, dumping whole files to see three lines, unbounded
searches, and re-deriving what an earlier session already worked out. Everything
runs locally. No account, no hosted service, and telemetry is off unless you
opt in twice.
The local dashboard: one ledger for every agent, every saving, and what the optimizer itself cost.
Quick start
Claude Code. Install the plugin rather than the bare MCP server: the plugin's
hooks do the saving, while the server alone only offers tools the model can ignore.
/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins
You need Node.js 22.14 or later on Claude Code's PATH, and Claude Code 2.1.139 or
later. Then check it works:
npx token-optimizer-doctor
The doctor feeds a synthetic payload to the real hook and confirms a large read is
handled. Every failure names its own fix.
Codex, Copilot CLI, Gemini CLI, Cursor and the rest. Every client runs the
same server, npx -y @ooples/token-optimizer-mcp@latest. Ready-made configuration
for each one is in src/integrations/, and
docs/INSTALLATION.md walks through all sixteen.
Requirements and what happens without them
- Node.js 22.14.0 or later, for the hooks and the MCP server.
node must be on
the PATH of the client process. If you just installed Node.js or Git, start the
client again from a new terminal so it picks up the new PATH.
- Claude Code 2.1.139 or later. The hooks use the exec form
(
"command": "node", "args": [...]). An older Claude Code ignores args, so the
hooks silently do nothing; the doctor reports it.
- If
node cannot start, the hooks let the tool call through
("onFailure": "continue"): you lose the savings, not the session. The MCP server
shows as disconnected in /mcp until Node is reachable.
Full details: docs/INSTALLATION.md.
Does it pay for itself?
Each mode was run on the same 10 SWE-bench Verified instances, paired against a
control session with no plugin. Resolution is graded by the official evaluator.
off lands at 1.00×, which is what it should do: with the hooks and the proxy
off, the product costs nothing extra and saves nothing.
| Run (SWE-bench Verified, Claude Sonnet) | Instances | Cost vs. control | Resolved, control / plugin |
|---|
Default mode (assist), first session | 10 | 0.705× [0.63–0.80] | 7 / 7 |
| Learned cost control, after the hoist fix | 15 | 0.634× [0.54–0.74] | 14 / 14 (of 15) |
off (MCP server only) | 10 | 0.999× [0.83–1.20] | 7 / 7 |
The samples are small and run-to-run variance is large, so read these as
directions with intervals, not guarantees. The full method, every run including
the ones where it lost, and the per-instance data are in
PR #559.
How it compares
Short answer: it saves more than every competitor we tested, in like-for-like
runs, except one small Claude Code task against Headroom, which is a tie. The
fairness notes and every loss are below the table.
| Competitor | How it was tested | Them | Token Optimizer | Result |
|---|
| Headroom | Tokens removed on Headroom's own benchmark, 18 workloads | 61.4% | 91.5% | ✅ Win |
| Headroom | Installed proxy vs ours, 120 Codex task pairs | $30.43 est. cost, 120/120 passed | $22.26 est. cost, 119/120 passed | ✅ 26.9% cheaper, 30.1% faster on average |
| Headroom | Installed proxy vs ours, one small Claude Code task, 4/4 tests | 48,626 weighted input | 49,053 weighted input | ➖ Tie (0.9% more) |
| tokenjuice | Product installed, same coding tasks for every arm | 13.6% cheaper | 33.6% cheaper | ✅ Win |
| Tokenade | Its rules text vs our rules text; its full product not yet run | 22.9% cheaper | 32.0% cheaper | ✅ Win |
| claude-token-optimizer | Product installed, its hooks fixed so they fire on Claude Code | 2.7% cheaper, within noise | 33.6% cheaper | ✅ Win |
How each row was kept fair, and what it does not show:
- claude-token-optimizer as shipped does nothing on Claude Code 2.1.251. Its
hooks read a
CLAUDE_TOOL_NAME variable that Claude Code does not set, so they
exit before checking anything. Scoring that would not be a fair comparison, so the row
uses their product with that one line changed to read the hook input Claude Code
actually sends. We confirmed the patched hooks fired and blocked oversized reads.
Its CLAUDE.md ships as an unfilled template, which understates it.
- Tokenade was run as its rules text only. That campaign recorded its CLI as
needing an account; it was later found to install without one, but the full
product has not been re-run. So it is compared with our rules text alone, not
our full product, and if its hooks save more, this row understates it.
- Headroom, first row: the 91.5% is our proxy. Like Headroom, it moves some
content out of the request for the agent to fetch back if needed. Our
compressor alone removes fewer tokens than Headroom on 9 of the 18 workloads.
- Headroom, Claude Code task: "weighted input" is input + 1.25 × cache
writes + 0.1 × cache reads, the way they are billed. It excludes output tokens.
- Headroom, 120 pairs: we wrote the 12 task families, including ones built to
make our proxy fail, and froze the plan before any run. Headroom's mode setting
is not recorded in that study. Our proxy crashed once (unknown usage) where
Headroom passed every task, and ours cost more on 30 of the 120 pairs. It is
cheaper on average, not on every task. Costs are over the 119 pairs where both
finished.
- The tokenjuice, Tokenade and claude-token-optimizer rows are one campaign:
1,050 runs on 2026-09-03, Claude Code 2.1.251, cost per finished task against
plain Claude Code. Any of these products may have changed since. The campaign
had no bias-control task, so a task set that happens to favour us cannot be
ruled out.
Beyond the table:
- ✅ Subscription plans go further. It detects a subscription and optimizes
for finished work per unit of quota, not per dollar. It spends leftover 5-hour
capacity only while your week is on pace. Limit monitors show your usage; this
acts on it.
- ✅ Tasks still get done. The same SWE-bench tasks were resolved with and
without it (7 of 7), at 0.71× the cost.
On Headroom's own benchmark, its fixtures and its harness, the proxy removes
91.5% of the tokens. Their best setting removes 61.4%. The proxy costs less
on 18 of 18 workloads when nothing it moved out is read back, and on 17 of 18
when all of it is.
Where it loses:
- Without the proxy, the compressor removes fewer tokens than Headroom on 9
of 18 workloads. On 8 of them Headroom moves content out of the request rather
than shrink it; on agentic-conversation it simply compresses better, 33.4%
against our 30.8%.
- Against Headroom, ours cost more on 30 of 120 task pairs and crashed once;
on one small Claude Code task Headroom used 0.9% fewer tokens.
- On one 342 KB-file task in the 2026-09-03 campaign, our hooks took about 6
minutes per run against 0.3 for plain Claude Code. It cost no more in tokens,
but it was slower.
- In the four-product run, most of the saving came from its rules file. The hooks
added no measurable cost saving on top.
Raw data: competitor campaign,
Headroom 120-pair study, and the Headroom
benchmark tables in the comparison.
What it does
- Stops the expensive call before it happens. On clients with a
pre-execution hook, an oversized
Read, Grep, cat or grep -r is routed to
a cached, bounded replacement, or refused outright in enforce mode. Re-reading a file you already read this
session returns only the diff.
- Remembers what your agent worked out. A per-project knowledge graph collects
findings, decisions and dead ends as a side effect of normal work, and feeds them
back when the agent touches the relevant file. Carrying a finding costs about 150
tokens; re-deriving it costs 5k–50k.
- Compresses what it cannot avoid. Tool output, logs, JSON and search results
are compressed with the prompt cache in mind: providers bill a cached prefix at
0.1× and a rewritten one at 1.25×, so it optimizes the bill, not the byte count.
- Measures itself and says when it is losing. Savings are recorded before and
after, with later expansions debited from the same total, and attributed per
client and per operation. Modeled savings are kept apart from measured ones.
- Works across 16 clients. Ten can have wasteful calls refused; six get
always-on routing rules where the host has no veto API.
How it works: the four mechanisms
- Hooks sit in front of the client's built-in tools. In
enforce mode a large
read is denied with a message naming the cheaper call; in the default assist
mode the hooks route, retrieve and capture without refusing anything.
- The proxy sits between the client and the provider, compressing request
bodies and keeping the cached prefix stable so cache reads stay cheap.
- The MCP server provides
smart_read, smart_grep, smart_edit,
optimize_text, token_audit and the rest: diff-on-reread, bounded search,
and an out-of-context store.
- The knowledge graph is written by the hooks as the agent works and read
back at the moment it is relevant.
More: docs/HOW_IT_WORKS.md.
The knowledge graph
you touch src/auth.ts
│
├─ verify() compares exp against the LOCAL clock (finding, 0.9)
├─ per-host retry budgets; global was rejected — deadlock (decision)
├─ ! the skew fix was reverted once already (dead end)
└─ [git] 47 changes in 90d, last three: "fix token expiry",
"revert skew fix", "fix token expiry again"
None of that is in your repository. It exists only because an agent once spent
tokens finding it out, and it is gone at the end of the session unless something
keeps it. No ingestion job, no embedding model, no rebuild step.
More: docs/HOW_IT_WORKS.md.
Modes: assist, enforce, advise, off
| Mode | What the hooks do |
|---|
assist (default) | Route, retrieve, capture and compress; refuse nothing |
enforce | Also refuse large built-in reads and unbounded searches |
advise | Suggest the cheaper call without refusing |
off | Hooks and proxy off; the MCP server's tools still work |
Set it with TOKEN_OPTIMIZER_MODE. The chart above shows what each mode cost on
SWE-bench.
Supported clients
Enforcing tier: the client has a pre-execution hook, so a wasteful call can be
refused.
Rules tier: Roo Code, Zed, Amp, Continue, Crush and Droid have no veto API, so
they get always-on routing rules instead.
Every config path is checked against the client's published documentation; see
docs/CLIENT_SUPPORT.md.
The dashboard
The dashboard reads the local ledger: verified savings, excluded reports,
per-agent attribution, hook health and the knowledge graph. It prices usage with
the exact provider, model and rate tier it captured, and leaves an ambiguous model
Not priced rather than guessing. More: docs/DASHBOARD.md.
Privacy and telemetry
- Nothing is measured about you unless you ask. Anonymous usage data takes two
separate opt-ins:
TOKEN_OPTIMIZER_TELEMETRY=1 counts into a file on your own
disk, and TOKEN_OPTIMIZER_BEACON=1 is what uploads it. DO_NOT_TRACK=1
overrides both.
- An event can hold only numbers and flags. A string is dropped before it is
written, so a path, prompt or error message cannot travel even by mistake. The
machine identifier is a salted hash, never your hostname.
- The version check runs only when you ask the doctor for a diagnosis, never
during a session.
TOKEN_OPTIMIZER_UPDATE_CHECK=0 turns it off.
npx token-optimizer-doctor prints which of these is on and what has been
recorded.
Full details: docs/HOW_IT_WORKS.md.
Verify the release, or remove it
Releases are published from CI with npm provenance, so
npm audit signatures ties the package to the workflow run and the commit without
trusting us. CHECKSUMS.sha256 ships alongside for offline checking.
To remove it, uninstall the plugin (/plugin uninstall token-optimizer@token-optimizer).
For a hook install, npx token-optimizer-uninstall shows the plan and changes
nothing; add --apply to carry it out. It removes only files that still match
what it wrote, and names anything you have edited since. Step by step:
docs/INSTALLATION.md.
Documentation
| Page | What is in it |
|---|
| How it works | The mechanisms, subagents, the knowledge graph, trust and attribution |
| Benchmarks and comparison | Head-to-head against Headroom, tokenjuice, Tokenade and claude-token-optimizer, what it does differently, where it loses |
| Installation | All sixteen clients, requirements, verification and removal |
| Reference | Tools, compression statistics and the full technical reference |
| Dashboard | What the local dashboard shows |
| OrcaRouter | Routing requests through OrcaRouter |
| Tool reference | Every MCP tool and its arguments |
| Token accounting | How savings are counted and priced |
Development
git clone https://github.com/ooples/token-optimizer-mcp.git
cd token-optimizer-mcp
npm ci
npm run build
npm test
The benchmarks, evaluation corpora and registry material live under
bench/. See CONTRIBUTING,
testing and the
security policy.
License
MIT. See LICENSE. Commercial use is allowed.