Compresses AI coding agent context to cut token costs, measure per-agent savings, and share a local knowledge graph across 16 CLI clients.
Also known as ooples/token-optimizer-mcp, @ooples/token-optimizer-mcp
- Stars
- 581
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 7.11.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is Token Optimizer MCP?
Token Optimizer compresses AI coding agent context to cut token costs, measure per-agent savings, and share a local knowledge graph across 16 CLI clients. It exposes 10 tools, such as wiki_write, wiki_query, expand.
Summary generated from the project's README
About Token Optimizer MCP server
Reducing the cost of AI coding agents while maintaining their performance is the primary goal of this tool. It functions by intercepting expensive operations like oversized file reads, searches, or redundant file access to prevent unnecessary token consumption. The system runs entirely on your local machine, requiring Node.js 22.14 or later, and does not require any external accounts or hosted services.
Developers using Claude Code can install a specific plugin to enable pre-execution hooks that automatically manage context. For other clients like Cursor, Copilot CLI, Gemini CLI, or Codex, the server can be run via npx to provide optimization tools. The system also maintains a local knowledge graph that tracks project decisions and findings across up to 16 different CLI clients, allowing different agents to share context without re-deriving information. A local dashboard provides visibility into per-agent savings and the specific costs incurred by the optimizer itself.
What you can do with it
- 1Minimize Claude Code expensesUse the plugin to ensure coding tasks are completed at a fraction of the standard token cost.
- 2Prevent redundant file readingStop agents from wasting tokens by re-reading files that have not changed during a session.
- 3Share context across multiple agentsMaintain a consistent knowledge graph so different CLI tools can access previous project findings.
Written from the project's README. Every use case is checked against a quote from it.
How to install Token Optimizer MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Token Optimizer MCP in Claude Code
$ claude mcp add token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcpInstall Token Optimizer MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"token-optimizer-mcp": {
"command": "npx",
"args": [
"-y",
"@ooples/token-optimizer-mcp"
]
}
}
}Install Token Optimizer MCP in VS Code
.vscode/mcp.json
{
"servers": {
"token-optimizer-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ooples/token-optimizer-mcp"
]
}
}
}Install Token Optimizer MCP in VS Code CLI
$ code --add-mcp '{"name":"token-optimizer-mcp","type":"stdio","command":"npx","args":["-y","@ooples/token-optimizer-mcp"]}'Install Token Optimizer MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"token-optimizer-mcp": {
"command": "npx",
"args": [
"-y",
"@ooples/token-optimizer-mcp"
]
}
}
}Install Token Optimizer MCP in Codex
$ codex mcp add token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcpInstall Token Optimizer MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.token-optimizer-mcp] command = "npx" args = ["-y", "@ooples/token-optimizer-mcp"]
Install Token Optimizer MCP in Gemini CLI
$ gemini mcp add -s user token-optimizer-mcp npx -- -y @ooples/token-optimizer-mcpInstall Token Optimizer MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"token-optimizer-mcp": {
"command": "npx",
"args": [
"-y",
"@ooples/token-optimizer-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @ooples/token-optimizer-mcp 7.11.0 in an isolated container with no network and no keys. It answered and listed 10 tools.
Token Optimizer MCP tools 10
Read from the server with tools/listwiki_writeActionRecord a durable finding in this project's knowledge graph so a later session retrieves it instead of re-deriving it. Use it the moment you conclude something that cost real work and is not obvious from the code: a dead end and why, a decision and its rejected alternatives, a command that finally worked, or how a subsystem fits together. Anchor it to the files it is about — the anchor is what lets the claim be invalidated when that code changes, and what makes it surface automatically when the file is next touched. Costs nothing and sends nothing off the machine.
wiki_queryRead-onlyRead the project's knowledge graph: fetch a finding by key, search findings by terms, inspect a node and its neighbours, or get the graph's audit, token balance and overall shape. Use it when the session index mentions a finding you want in full, or to find out what the graph holds at all. NOT for anchored retrieval: to ask what is known about a particular file or symbol, call wiki_read, which does exactly that and is the tool the enforcement layer points at.
expandRetrieve the full output behind a preview reference, served from the local store rather than by re-running anything. Pass `section` to say which named part of the preview you needed -- that is what teaches the next preview to keep it. Pass `claim` and `anchor` to record what you learned, so the same expansion never happens again.
optimize_sessionAnalyzes operations in the current session from the session JSONL log, identifies large text blocks from file-based tools (Read, Write, Edit), compresses them, and stores them in the cache to reduce future token usage. Returns a summary of the optimization.
smart_readRead-onlyRead files with intelligent caching, diff-based updates, and syntax-aware optimization. Measured token reduction vs reading the file: -2% to 0% first read, 99-99.9% repeated on an unchanged file (bench/tools, 3 fixtures) -- a first read returns the file plus a one-field header, so it still costs a little more than reading the file; the saving is on the repeat.
smart_writeWrite files with an unmeasured design target of 85% token reduction through verification, atomic operations, and change tracking
smart_editEdit files with an unmeasured design target of 90% token reduction through line-based operations and diff-only output
smart_globRead-onlySearch files with glob patterns and an unmeasured design target of 75% token reduction through path-only results and smart filtering
smart_grepRead-onlySearch file contents with an unmeasured design target of 80% token reduction through match-only output and smart filtering
get_optimization_reportGet a provenance-gated token report. Verified savings require a materialized MCP payload before and after optimization; historical and tool-reported estimates are excluded. Direct API-price equivalents use each exact captured model and route; ambiguous operations remain unpriced.
| wiki_write | Record a durable finding in this project's knowledge graph so a later session retrieves it instead of re-deriving it. Use it the moment you conclude something that cost real work and is not obvious from the code: a dead end and why, a decision and its rejected alternatives, a command that finally worked, or how a subsystem fits together. Anchor it to the files it is about — the anchor is what lets the claim be invalidated when that code changes, and what makes it surface automatically when the file is next touched. Costs nothing and sends nothing off the machine. | Action |
| wiki_query | Read the project's knowledge graph: fetch a finding by key, search findings by terms, inspect a node and its neighbours, or get the graph's audit, token balance and overall shape. Use it when the session index mentions a finding you want in full, or to find out what the graph holds at all. NOT for anchored retrieval: to ask what is known about a particular file or symbol, call wiki_read, which does exactly that and is the tool the enforcement layer points at. | Read-only |
| expand | Retrieve the full output behind a preview reference, served from the local store rather than by re-running anything. Pass `section` to say which named part of the preview you needed -- that is what teaches the next preview to keep it. Pass `claim` and `anchor` to record what you learned, so the same expansion never happens again. | |
| optimize_session | Analyzes operations in the current session from the session JSONL log, identifies large text blocks from file-based tools (Read, Write, Edit), compresses them, and stores them in the cache to reduce future token usage. Returns a summary of the optimization. | |
| smart_read | Read files with intelligent caching, diff-based updates, and syntax-aware optimization. Measured token reduction vs reading the file: -2% to 0% first read, 99-99.9% repeated on an unchanged file (bench/tools, 3 fixtures) -- a first read returns the file plus a one-field header, so it still costs a little more than reading the file; the saving is on the repeat. | Read-only |
| smart_write | Write files with an unmeasured design target of 85% token reduction through verification, atomic operations, and change tracking | |
| smart_edit | Edit files with an unmeasured design target of 90% token reduction through line-based operations and diff-only output | |
| smart_glob | Search files with glob patterns and an unmeasured design target of 75% token reduction through path-only results and smart filtering | Read-only |
| smart_grep | Search file contents with an unmeasured design target of 80% token reduction through match-only output and smart filtering | Read-only |
| get_optimization_report | Get a provenance-gated token report. Verified savings require a materialized MCP payload before and after optimization; historical and tool-reported estimates are excluded. Direct API-price equivalents use each exact captured model and route; ambiguous operations remain unpriced. |
Configuration
ORCAROUTER_API_KEYTOKEN_OPTIMIZER_CACHE_DIRDirectory path for cache storage (optional, defaults to ~/.token-optimizer-cache)
TOKEN_OPTIMIZER_LARGE_READ_BYTESTOKEN_OPTIMIZER_MODETOKEN_OPTIMIZER_ORCA_MODELTOKEN_OPTIMIZER_ROLLOUT_CHANNEL
| Name | Description | |
|---|---|---|
| ORCAROUTER_API_KEY | — | |
| TOKEN_OPTIMIZER_CACHE_DIR | Directory path for cache storage (optional, defaults to ~/.token-optimizer-cache) | |
| TOKEN_OPTIMIZER_LARGE_READ_BYTES | — | |
| TOKEN_OPTIMIZER_MODE | — | |
| TOKEN_OPTIMIZER_ORCA_MODEL | — | |
| TOKEN_OPTIMIZER_ROLLOUT_CHANNEL | — |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableooples/token-optimizer-mcp is public and reachablegithub.com/ooples/token-optimizer-mcp ↗Pass
- Package names this repository as its source@ooples/token-optimizer-mcp names ooples/token-optimizer-mcp as sourcenpmjs.com/package/@ooples/token-optimizer-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @ooples/token-optimizer-mcpnpmjs.com/package/@ooples/token-optimizer-mcp/v/7.11.0#prove ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/ooples/token-optimizer-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @ooples/token-optimizer-mcpPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubHow it compares to Alternative A
Providers cache the prompt prefix: cached tokens re-read at 0.1x, rewritten ones bill at 1.25x. Most compressors optimise bytes removed and ignore that multiplier. This one optimises the bill.
Measured against their real implementation, on their own fixtures. Not a reimplementation and not our fixtures: their harness compresses the payload, dumps it, their resolver redeems their own markers, and ours is handed the identical bytes. Their column is the best of the nine configurations that capture holds, row by row.
Two of our arms are in the table, and they answer different questions. ours
is the block engine with nowhere to move a block, which is how the MCP tools and
the hooks run: everything it removes, it removes by compressing, and nothing
leaves the request. ours, proxy is the proxy a Claude Code session runs
through, which also moves a block it could not compress out to a file and
leaves a marker naming the path -- the same kind of trade their content-cache
reference makes. ours, preset is the block engine with that move switched on
at spillWholeBlockBelow: 0.9.
| workload | payload | theirs | ours | ours, proxy | ours, preset | zero-turn ids |
|---|---|---|---|---|---|---|
| agentic-conversation | 244,908 | 37.3% / 33.4% | 42.9% / 30.8% | 52.4% / 49.0% | 100.0% / 100.0% | 2099 / 2099 / 0 |
| agent-loop | 170,938 | 42.2% / 54.3% | 69.3% / 59.1% | 92.0% / 94.1% | 93.6% / 94.3% | 185 / 185 / 52 |
| agent-loop-logs | 327,500 | 51.5% / 53.0% | 61.9% / 58.1% | 88.7% / 91.5% | 96.2% / 97.0% | 2034 / 2034 / 81 |
| api-responses | 49,127 | 88.2% / 89.3% | 66.6% / 59.1% | 96.4% / 96.8% | 96.6% / 96.8% | 699 / 98 / 23 |
| browser-session | 781,774 | 21.7% / 13.1% | 93.7% / 26.5% | 55.5% / 90.2% | 100.0% / 99.9% | 334 / 334 / 0 |
| code-search | 131,264 | 47.4% / 59.7% | 81.8% / 70.8% | 97.7% / 97.9% | 95.7% / 96.1% | 201 / 201 / 43 |
| database-rows | 45,929 | 88.6% / 89.2% | 65.6% / 56.5% | 92.4% / 93.1% | 92.6% / 93.4% | 590 / 78 / 49 |
| codebase-exploration | 137,961 | 99.7% / 99.7% | 16.0% / 12.7% | 99.6% / 99.6% | 100.0% / 99.9% | 540 / 3 / 0 |
| grep-output | 75,219 | 99.6% / 99.6% | 56.1% / 51.9% | 99.5% / 99.6% | 99.9% / 99.9% | 1005 / 3 / 0 |
| log-entries | 91,385 | 80.8% / 83.2% | 63.5% / 52.0% | 95.4% / 95.7% | 95.5% / 96.0% | 1180 / 237 / 46 |
| human-authored-json | 37,425 | 30.6% / 30.0% | 66.6% / 66.0% | 81.6% / 83.7% | 96.7% / 96.9% | 154 / 154 / 11 |
| issue-triage | 109,354 | 53.1% / 55.2% | 88.1% / 85.7% | 97.2% / 97.6% | 95.1% / 95.7% | 59 / 59 / 21 |
| rag-conversation | 171,913 | 0.0% / 0.1% | 84.6% / 83.2% | 99.1% / 99.4% | 100.0% / 100.0% | 42 / 42 / 0 |
| raw-build-log | 158,057 | 99.8% / 99.8% | 70.6% / 48.2% | 99.7% / 99.8% | 100.0% / 100.0% | 430 / 3 / 0 |
| relevance-probe | 49,157 | 64.1% / 71.0% | 82.4% / 77.2% | 97.1% / 97.8% | 95.8% / 96.6% | 225 / 225 / 13 |
| search-results | 96,647 | 95.0% / 95.4% | 74.3% / 59.4% | 96.5% / 96.5% | 96.6% / 96.6% | 505 / 62 / 34 |
| repeated-reads | 158,285 | 37.4% / 30.4% | 71.7% / 68.5% | 99.5% / 99.6% | 100.0% / 100.0% | 394 / 388 / 0 |
| sre-debugging | 312,276 | 88.4% / 89.9% | 67.4% / 62.4% | 98.5% / 98.7% | 97.1% / 97.5% | 3116 / 506 / 82 |
Recorded 2026-10-17 at b1231a8c, by the command in the
record's regenerate field, over Alternative A's own fixtures and harness. That arm runs
Alternative A itself, so CI does not re-derive it -- it checks these figures and
this provenance against the record instead.
Over the corpus the proxy removes 82.5% of the characters and 91.5% of the tokens; their best configuration removes 51.5% and 61.4%. It is cheaper than their best arm on 18 of 18 rows when nothing is ever fetched back, which is the end of the range their markers are built for, and on 17 of 18 when every moved block is fetched back. The block engine alone removes 72.0% and 55.9%: more of the characters than theirs, fewer of the tokens.
Where they still win, and why. On codebase-exploration, grep-output,
raw-build-log, sre-debugging and the four raw-data rows their best arm takes
83.2-99.8% off the tokens and the block engine 12.7-62.4%. Their number there is
a content-cache reference: the block is not made smaller, it is taken out of
the request, put in a store, and replaced by a <<ccr:hash,kind,size>> marker.
An engine with nowhere to put a block cannot match that, so on those rows the
ours column loses on reduction, and on cost when nothing is fetched back. The
proxy makes the same move: it is ahead of them on five of those eight rows, level
on grep-output and raw-build-log, and a tenth of a point behind on
codebase-exploration. The one row where the proxy costs more than they do is
agentic-conversation, and only when every block it moved is fetched back:
they move none of that conversation out, so they cost the same at either end,
while the proxy moves part of it and pays a retrieval for each part it wants
back.
The other column is a turn. A marker is not the content: to read what it stands for, the agent spends a request. Of the 13,792 retention units planted in the corpus, the block engine keeps 5,223 in the text and 8,569 more rebuildable from the text alone, so every one of them is there with no extra turn; theirs keeps 6,711 in the text and 7,075 behind its store, one retrieval call away. 0 are unrecoverable on our side and 6 on theirs. Their best arms force 17 round trips across the corpus to get their content back; the block engine forces 0. The proxy, like theirs, trades a turn for every block it moves, and that turn is what the fetch-rate end of the cost model prices.
What their marker costs is priced, not just its size. Their marker is only
redeemable because their proxy also sends a alternative_a_retrieve tool with the
request -- on by default (ccr_inject_tool), and on every later request once a
session has used it -- so every row where their best arm leaves a marker is
charged for that tool's definition as well, recorded from their own package by
bench/compression/alt-a/ccr-tool.py. The turn that first adds the tool also
rewrites the whole cached prefix behind it; that is not charged, which errs in
their favour. Ours needs no tool: our marker names a path the agent opens with
the Read it already has, and the path is priced at the length the proxy really
writes (<home>/.tok/<pid>/<15 digits>, src/compress/spill-path.ts) rather than
a shorter invented one.
browser-session is mostly the fixture. This payload holds four images, two
of them distinct, and the base64 in them is generated rather than photographic:
one distinct image alone folds from 160,032 characters to 5,572, which no real
PNG would do. What carries over to a real session is the duplication -- half the
image bytes are a second copy of an image already in the request, which is
44.3% of the whole payload. The run the marker names is still in the output
above it, so the reader rebuilds it without asking for anything, which is why
the characters fall much further than the tokens: the image tokens are counted
from pixels on both arms either way.
Reproduce the whole table:
python bench/compression/alt-a/run-theirs.py <alt-a-clone> <out-dir>
python bench/compression/alt-a/resolve-theirs.py <alt-a-clone> <out-dir>
node bench/compression/head-to-head.mjs <out-dir>
Against their published design
A second arm reimplements their published design from their own benchmark
generator's definitions — opaque hash markers, history compressed, a retrieval
tool and system message injected — so the four workloads with a published
comparator can be checked without their clone. node bench/compression/proof.mjs:
| workload | payload | theirs | ours | verdict |
|---|---|---|---|---|
| code-search | 17765 | 92.1% | 97.8% | ours |
| sre-debugging | 65694 | 92.2% | 98.6% | ours |
| issue-triage | 54174 | 72.8% | 97.5% | ours |
| codebase-exploration | 78502 | 47.4% | 54.7% | ours |
Four workloads, because those are the four this arm has a published comparator for. The head-to-head harness scores eighteen; the other fourteen are not in this arm, and are scored against their real implementation in the table above.
codebase-exploration was theirs and is now ours, by 7.3 points. An earlier
version of this table claimed 61.3% for us on that row, then parity, then a
published loss at 46.0% against their 47.4%. The first two were figures from a
branch rather than from here; the third was true on this tree when it was
written; four log engine commits then moved it to 54.2%, masking an interior
hashbang so a concatenated block still parses moved it to 64.9%, and
authenticating every marker with a six-character stamp took 0.2 of a point
back, and naming a spilled file by a digest of its contents, the way the proxy
sink really names it, instead of by its position in a counter, took another
half point, to reach 64.2%. Then the currency stopped being an estimate: every
figure in the table above is now the count Anthropic's own tokenizer returns
for the text, recorded into a committed fixture so this stays offline, and
under it the row reads 53.7%, and pricing the path the proxy's sink really
writes -- content-addressed and decimal, where this arm had invented a 32-digit
hex name -- moved it to 54.7%. That is the largest move in this history and
the only one that is not about the engine at all. Dividing characters by four
had been charging the control's hex markers too much and our own stamp far too
little -- the stamp was six characters of a vowelless base-31 alphabet then,
and a random string over a large alphabet is close to the worst case a BPE
tokenizer has, so it cost a measured 5.52 tokens where chars/4 billed 2. Those
three are the only figures here that moved the wrong way, and none of them is a
regression: each is the harness charging us for something it had been leaving
out. Being able to see that cost is what paid for the next move: the stamp is
now nine decimal digits, which carry slightly more entropy than those six
characters did and cost 4 tokens on every draw rather than a mean of 5.52 that
ranged from four to seven. Measured against the old stamp on this row -- the
same tree, the same fixture, only the stamp pinned back to its base-31 form --
that bought a tenth of a point, and a tenth is the honest size of it: a
marker got better than a quarter cheaper, but markers are a small part of what
the engine emits, so the headline moves far less than the per-marker saving
suggests. A
number in prose is a fact about the tree it was measured on, which is why
bench/compression/readme-table.check.mjs re-derives every figure in the block
above from the harness rather than trusting it.
Against the four comparators in this reimplemented arm: ours on all four. Against their real implementation the answer is the table at the top of this section, and it is a split rather than a sweep: the proxy is cheaper than their best arm on every row when nothing is fetched back and takes more of the tokens overall, while the block engine alone keeps every identifier without a turn and loses on reduction wherever their best arm moves a block out of the request.
The two columns come from different arms of the same engine, and that is the
point. v3-history compresses history too and matches them byte for byte;
v1-frontier leaves the cached prefix alone and wins the invoice by 11–42%.
Maximising bytes removed is available and is not the default, because on a
cached prefix it costs money.
The competitor arm is this repository's reimplementation of their published design — opaque hash markers, history compressed, a retrieval tool and system message injected — not their binary, and it is held to the same signed-content guard we hold ourselves to.
On whole sessions
node bench/compression/session-replay.mjs replays real recorded conversations
turn by turn and prices each the way a provider does. Four independent sessions,
whole request including system prompt and tool schema, against no proxy:
| conversation length | ours | cheaper on |
|---|---|---|
| 10 turns | 0.953x | 4 of 4 |
| 20 turns | 0.915x | 4 of 4 |
This is the region nothing else touches: conversation history is ~65% of a live request and the only part that grows every turn. The saving grows with session length, because model reasoning accumulates.
On end-to-end agent tasks
THOL, 16 real tasks against a no-proxy control:
- cheaper on 11 of 16 tasks
- median cost 0.926x, median turns 0.671x
- zero quality cost: mean score 0.994 against control's 0.994, lower on 0 of 16 tasks
One run per task, so the aggregate interval still spans 1.0; the per-task tally and the score parity are the solid parts. Every figure here is regenerated from the committed benchmarks, which ship in this repository.
The 30-second version
Your agent burns most of its context on work it already did: re-reading files that have not changed, dumping a whole file to see three lines, running unbounded searches, and re-deriving conclusions it reached last session and then forgot.
Token Optimizer attacks that on four fronts.
1. It makes the expensive call impossible. Install the plugin and a built-in
Read of a 200 KB file is denied, with the refusal naming the cached,
diffed replacement. Same for Grep, Glob, Edit, Write, and cat /
head / grep -r through the shell. Re-reading a file you already read this
session returns only a diff — usually the single biggest win, and one that
size-based rules structurally cannot catch. There is no setting to turn on.
2. It remembers what your agent worked out. A per-project knowledge graph accumulates findings, decisions and dead ends as a side effect of working, then feeds them back the moment the agent touches the relevant file. A finding costs ~150 tokens to carry. Re-deriving it costs 5k–50k.
3. It measures itself, in public, and tells you when it is losing. A materialized before/actual-return measurement for MCP progressive disclosure, with later expansions debited from the same net. Modeled graph substitutions and the randomized control arm for downstream graph effects remain separate. Every number is measured, visibly collecting, excluded, or absent.
4. It attributes the traffic. Returned context, optional cost equivalents, and net transport avoided are grouped by operation and MCP handshake identity. Codex, Claude Code, Gemini, and any other connected client get separate rows. Old records without identity remain explicitly unattributed instead of being assigned to whichever agent happens to be open now.
No account and no hosted service. MIT, so it is usable at work.
Nothing is measured about you unless you ask for it. Anonymous usage data is
off by default and takes two separate opt-ins: TOKEN_OPTIMIZER_TELEMETRY=1
aggregates counts into a file on your own disk, and TOKEN_OPTIMIZER_BEACON=1
is what uploads any of it. Setting the first opens no socket. With both set,
the events already on disk are sent once per session at start-up -- in a batch,
never on the hot path -- and the file is cleared only after the receiver has
accepted them. install_doctor prints which of the two is on, how many events
are waiting and where they would go; it reports without sending. A package
built without the upload key cannot transmit at all, and the doctor says so
rather than letting an opt-in look like it is working.
DO_NOT_TRACK=1 overrides both, whatever else is set. The version check
npm run doctor and install_doctor make is a plain GET to the registry npm
installs from, carries nothing about you, and runs only when you ask for a
diagnosis -- never during a session. DO_NOT_TRACK=1 or
TOKEN_OPTIMIZER_UPDATE_CHECK=0 suppresses it before a socket is opened. An event may only
contain numbers and flags -- a string is dropped before it is written, so a
path, a prompt or an error message cannot travel even by mistake -- and the
machine identifier is a salted hash, never your hostname. What the counts are
about is the hook ledger your own project already keeps: how often the graph
answered instead of a tool, what each arm of the holdout was delivered and
withheld, and whether the saving exceeded the cost -- reduced to integers once
every six hours, never the ledger itself, which names your files. Usage is
counted as a rollup rather than a row per request: one event per 200 requests,
holding the request count, bytes in and out, how often compression paid, how
often knowledge was injected, and how many blocks were elided, plus one final
event when the proxy stops. That keeps the totals exact -- a row per request
would overflow the batch on a busy session and leave you reporting its first
five hundred -- at the cost of the per-request distribution, which is not
something anyone downstream needs. npm run doctor
prints exactly which of these is on and what has been recorded.
What the dashboard proves on a real machine
The screenshots in this README come from the shipped server reading persisted local data, not a design mockup. In the capture above it reports:
- 43,491 net verified MCP transport tokens avoided in the current live proof: 54,037 gross reduction minus a deliberate 10,546-token expansion;
- 486,074,740 historical/tool-reported tokens quarantined, dominated by repository scan volume that never entered model context;
- a live Codex / Claude Code / Gemini stdio smoke against AiDotNet, with each client attributed independently;
- 2,648 graph nodes, 6,527 edges, and 58 findings across 11 local projects;
- more than 1,000 hook runs with zero failures and zero timeouts across six active CLI clients in the selected rolling 24-hour window;
- 6,332 tokens of modeled graph-substitution potential, excluded from the
verified headline while the causal graph-reuse study remains
Collecting.
The dashboard now reads native CLI usage receipts and prices uncached input, cache reads, cache writes, and output with the exact captured provider, model, route, request-time tier, and versioned official source. Ambiguous model ids stay Not priced instead of receiving a blended guess. API/list-price equivalents are kept separate from provider-reported charges and are never labeled as a subscription invoice. See the token accounting contract.
Quick start
Claude Code — install the plugin, not the bare MCP server. The plugin is what enforces; adding the server alone just gives the model tools it can ignore.
/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins
That is the entire installation. All sixteen clients →
Then, whenever you want to know what to do next:
token_audit
One ranked queue: what is costing the most per session, with an optional monthly cost equivalent only after you configure your own effective rate. Each line names how to fix it. Not a dashboard, not six reports — a queue.
Subagents and workflows
Agents are where token spend concentrates. A long-running subagent re-sends its whole context on every turn, so every byte a tool adds is paid for again on each later turn. In one measured session, 42 workflow subagents made 4,483 model calls. The six longest made 218–348 calls each and peaked at 336K–609K tokens of context. Together they spent 4.0M output tokens and 1.0B cache-read tokens. The bill is the re-reading, not the writing.
Token Optimizer MCP questions
How do I add Token Optimizer MCP to Claude Code?
Run claude mcp add token-optimizer-mcp -- npx -y @ooples/token-optimizer-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Token Optimizer MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Token Optimizer MCP provide?
It exposes 10 tools, including wiki_write, wiki_query, expand, optimize_session, smart_read.
How much does Token Optimizer reduce token usage?
Over its benchmark corpus the proxy removes 82.5% of characters and 91.5% of tokens, while the block engine alone removes 72.0% and 55.9%.
Does Token Optimizer send telemetry?
No, telemetry is opt-in and off by default.
What license does Token Optimizer use?
It is MIT licensed and commercial use is allowed.
What Node.js version does Token Optimizer require?
It requires Node.js 22.14 or newer.