![\"Token](\"docs/assets/logo-400.png\"){kind=logo}
\n\n \n
\n Compression that optimises your bill, not your byte count —\n and ships the benchmark so you can check it.\n
\n\n\n ![\"npm](\"https://img.shields.io/npm/v/%40ooples%2Ftoken-optimizer-mcp?logo=npm\")
![\"CI\"](\"https://github.com/ooples/token-optimizer-mcp/actions/workflows/ci.yml/badge.svg?branch=master\"){kind=icon}
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n ![\"Node.js](\"https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white\"){kind=icon}
\n ![\"Measured](\"https://img.shields.io/badge/measured-on%20two%20harnesses-2ea043\"){kind=icon}
![\"16](\"https://img.shields.io/badge/clients-16-8b5cf6\"){kind=icon}
![\"Direct](\"https://img.shields.io/badge/direct%20savings-before%20%2F%20actual%20return-3b82f6\"){kind=icon}
![\"Telemetry](\"https://img.shields.io/badge/telemetry-opt--in-2ea043\"){kind=icon}
![\"MIT,](\"https://img.shields.io/badge/commercial%20use-MIT%2C%20allowed-0d9488\"){kind=icon}
\n ![\"Live](\"./docs/media/live/overview-live.png\")
\n
One local ledger for optimizer tools, live-graph substitutions, every agent, and the graph's own cost.
\n\n---\n\n## Why it wins\n\nProviders cache the prompt prefix: cached tokens re-read at **0.1x**, rewritten\nones bill at **1.25x**. Most compressors optimise bytes removed and ignore that\nmultiplier. This one optimises the bill.\n\n**It wins both columns.** Against a faithful reimplementation of the leading\nopen compressor's published design, `node bench/compression/proof.mjs`:\n\n\n\n| workload | payload | theirs | ours | verdict |\n| -------------------- | ------: | -----: | -----: | ------- |\n| code-search | 17765 | 92.1% | 97.6% | ours |\n| sre-debugging | 65694 | 92.2% | 98.4% | ours |\n| issue-triage | 54174 | 72.8% | 97.3% | ours |\n| codebase-exploration | 78502 | 47.4% | 46.0% | theirs |\n\n\n\nFour workloads, because those are the four with a published comparator. The\nharness reports twelve; the other eight are ours alone and are not a\nhead-to-head.\n\n**`codebase-exploration` is theirs, by 1.4 points.** An earlier version of this\ntable claimed 61.3% for us on that row, and a later one claimed parity; both\nwere figures from a branch rather than from here. Measured on this tree it is\n46.0% against their 47.4%, and it is published as a loss because that is what\nit is. A number in prose is a fact about the tree it was measured on, which is\nwhy `bench/compression/readme-table.check.mjs` re-derives every figure in the\nblock above from the harness rather than trusting it.\n\n**Reduction is not the only column, and the other one goes to them.** Scored\nsymmetrically on their own fixtures, of 3,793 retention units they keep **1,890**\ndirectly visible in the text they send and we keep **345** — we reach a higher\nreduction partly by eliding harder, into a spill about 0.94x the size of the\ninput. Nothing is unrecoverably lost on our side, and a retrieval costs a turn.\nBoth numbers belong in any quote of either.\n\nAgainst the four published comparators: **ours on 3, theirs on 1.**\nThe tally is over comparators, not over workloads -- the harness runs twelve\nand eight of them have nothing to compare against.\n\nThe two columns come from different arms of the same engine, and that is the\npoint. `v3-history` compresses history too and matches them byte for byte;\n`v1-frontier` leaves the cached prefix alone and wins the invoice by 11–42%.\nMaximising bytes removed is available and is not the default, because on a\ncached prefix it costs money.\n\nThe competitor arm is this repository's reimplementation of their published\ndesign — opaque hash markers, history compressed, a retrieval tool and system\nmessage injected — not their binary, and it is held to the same signed-content\nguard we hold ourselves to.\n\n### On whole sessions\n\n`node bench/compression/session-replay.mjs` replays real recorded conversations\nturn by turn and prices each the way a provider does. Four independent sessions,\nwhole request including system prompt and tool schema, against no proxy:\n\n| conversation length | **ours** | cheaper on |\n| ------------------- | ---------- | ---------- |\n| 10 turns | **0.953x** | **4 of 4** |\n| 20 turns | **0.915x** | **4 of 4** |\n\nThis is the region nothing else touches: conversation history is ~65% of a live\nrequest and the only part that grows every turn. The saving grows with session\nlength, because model reasoning accumulates.\n\n### On end-to-end agent tasks\n\nTHOL, 16 real tasks against a no-proxy control:\n\n- **cheaper on 11 of 16 tasks**\n- **median cost 0.926x**, **median turns 0.671x**\n- **zero quality cost**: mean score **0.994** against control's **0.994**,\n lower on **0 of 16 tasks**\n\nOne run per task, so the aggregate interval still spans 1.0; the per-task tally\nand the score parity are the solid parts. Every figure here is regenerated from\nthe committed benchmarks, which ship in this repository.\n\n## The 30-second version\n\nYour agent burns most of its context on work it already did: re-reading files\nthat have not changed, dumping a whole file to see three lines, running\nunbounded searches, and re-deriving conclusions it reached last session and then\nforgot.\n\nToken Optimizer attacks that on four fronts.\n\n**1. It makes the expensive call impossible.** Install the plugin and a built-in\n`Read` of a 200 KB file is **denied**, with the refusal naming the cached,\ndiffed replacement. Same for `Grep`, `Glob`, `Edit`, `Write`, and `cat` /\n`head` / `grep -r` through the shell. **Re-reading a file you already read this\nsession returns only a diff** — usually the single biggest win, and one that\nsize-based rules structurally cannot catch. There is no setting to turn on.\n\n**2. It remembers what your agent worked out.** A per-project knowledge graph\naccumulates findings, decisions and dead ends as a side effect of working, then\nfeeds them back the moment the agent touches the relevant file. A finding costs\n~150 tokens to carry. Re-deriving it costs 5k–50k.\n\n**3. It measures itself, in public, and tells you when it is losing.** A\nmaterialized before/actual-return measurement for MCP progressive disclosure,\nwith later expansions debited from the same net. Modeled graph substitutions\nand the randomized control arm for downstream graph effects remain separate.\nEvery number is measured, visibly collecting, excluded, or absent.\n\n**4. It attributes the traffic.** Returned context, optional cost equivalents,\nand net transport avoided are grouped by operation and MCP handshake identity. Codex, Claude Code,\nGemini, and any other connected client get separate rows. Old records without\nidentity remain explicitly unattributed instead of being assigned to whichever\nagent happens to be open now.\n\nNo account, no telemetry, no hosted service. MIT, so it is usable at work.\n\n### What the dashboard proves on a real machine\n\nThe screenshots in this README come from the shipped server reading persisted\nlocal data, not a design mockup. In the capture above it reports:\n\n- **43,491 net verified MCP transport tokens avoided** in the current live\n proof: 54,037 gross reduction minus a deliberate 10,546-token expansion;\n- **486,074,740 historical/tool-reported tokens quarantined**, dominated by\n repository scan volume that never entered model context;\n- a live Codex / Claude Code / Gemini stdio smoke against AiDotNet, with each\n client attributed independently;\n- **2,648 graph nodes, 6,527 edges, and 58 findings** across 11 local projects;\n- **more than 1,000 hook runs with zero failures and zero timeouts** across six\n active CLI clients in the selected rolling 24-hour window;\n- **6,332 tokens of modeled graph-substitution potential**, excluded from the\n verified headline while the causal graph-reuse study remains `Collecting`.\n\nThe dashboard now reads native CLI usage receipts and prices uncached input,\ncache reads, cache writes, and output with the exact captured provider, model,\nroute, request-time tier, and versioned official source. Ambiguous model ids stay\n**Not priced** instead of receiving a blended guess. API/list-price equivalents\nare kept separate from provider-reported charges and are never labeled as a\nsubscription invoice. See the [token accounting contract](./docs/TOKEN_ACCOUNTING.md).\n\n## Quick start\n\n**Claude Code** — install the plugin, not the bare MCP server. The plugin is\nwhat enforces; adding the server alone just gives the model tools it can ignore.\n\n```text\n/plugin marketplace add ooples/token-optimizer-mcp\n/plugin install token-optimizer@token-optimizer\n/reload-plugins\n```\n\nThat is the entire installation. [All sixteen clients →](#installation)\n\nThen, whenever you want to know what to do next:\n\n```text\ntoken_audit\n```\n\nOne ranked queue: what is costing the most per session, with an optional monthly\ncost equivalent only after you configure your own effective rate. Each line\nnames how to fix it. Not a dashboard, not six reports — a queue.\n\n---\n\n## The knowledge graph — the part nothing else has\n\nEvery agent session ends the same way: the reasoning evaporates. The next\nsession re-derives it, at full price, forever.\n\nThis builds a **living per-project graph** — nodes for files, symbols, tasks and\nfindings; edges for `derived_from`, `contains`, `supersedes`, `contradicts`,\n`related` — and it fills itself in from real work. No ingestion job, no\nembedding model, no rebuild step, no query to formulate.\n\n```\nyou touch src/auth.ts\n │\n ├─ verify() compares exp against the LOCAL clock (finding, 0.9)\n ├─ per-host retry budgets; global was rejected — deadlock (decision)\n ├─ ! the skew fix was reverted once already (dead end)\n └─ [git] 47 changes in 90d, last three: \"fix token expiry\",\n \"revert skew fix\", \"fix token expiry again\"\n```\n\nNone of that is in your repository. It exists only because an agent once burned\ntokens finding it out — and every other tool throws it away at the end of the\nsession.\n\n**What a default install actually produces.** The structural graph — files,\nsymbols, tasks, and the edges between them — is captured from ordinary tool\ntraffic with no configuration at all. Findings are produced two ways. At session\nend, `derive` reads evidence already on disk (command outcomes and exit codes,\nred-to-green transitions, corrections, re-read churn) and writes findings from\nit: no model call, no credential, nothing sent anywhere. And the active model\nrecords durable conclusions itself through `wiki_write`.\n\nThe **model-based semantic harvest** is the third path, and the only one that\nneeds something you do not already have. It is **not opt-in** —\n`TOKEN_OPTIMIZER_HARVEST=0` turns it _off_ — but its real gate is a credential:\nwith none it reports `off:no-key`, which is the state on CI, corporate machines,\nand subscription-only logins. Point `TOKEN_OPTIMIZER_HARVEST_ENDPOINT` at a\nlocal model and it runs **free and private, with nothing leaving the machine**.\n`npx token-optimizer-doctor` states which of these is live.\n\n### Why this is not RAG\n\n| Classic RAG | This |\n| -------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| Retrieves **evidence**; the model re-derives meaning each time | Retrieves **verdicts** — the reasoning already happened |\n| Index built by a **batch ingestion job** | Accretes from **real agent traffic** — coverage follows attention |\n| **Similarity** search | **Traversal** — this symbol _and its callers_ |\n| Model must **formulate a query** | Fires when the model **reaches for a file** |\n| Staleness **invisible**; serves rotted chunks confidently | Staleness **computed** from content hashes, served with the invalidating diff |\n| Returns only what is **in the documents** | Returns **dead ends**, which exist nowhere in your source tree |\n\nTraversal plus lexical search: deterministic, instant, explainable, and it works\noffline.\n\n### The zero-turn refusal\n\nA plain deny costs a full turn: the model calls `Read`, is refused, re-plans,\ncalls `smart_read`. But at refusal time we already hold the file _and_ the\nsnapshot the graph stored — so the refusal **carries the answer inside it**.\nNothing to re-plan, no second call. Turn cost drops from one to zero.\n\nAnd when the graph already holds the verdict a tool output would support, the\noutput never enters context at all. Not compressed. Absent.\n\n---\n\n## The dashboard\n\n```bash\nnpm install\nnpm run build\nnpm run dashboard # http://localhost:3100\n```\n\n\n ![\"Per-agent](\"./docs/media/live/agent-accounting-live.png\")
\n
\n ![\"Structured](\"./docs/media/live/capture-health-live.png\")
\n
\n ![\"Direct](\"./docs/media/live/graph-balance-live.png\")
\n
\n ![\"Interactive](\"./docs/media/live/graph-explorer-live.png\")
\n