Token Optimizer

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 three 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 randomized control arm for savings. A forecast that keeps its own accuracy record. Cache economics read from your client's own transcript rather than modelled. Every number here is measured or absent — never estimated and presented as fact.

No account, no telemetry, no hosted service. MIT, so it is usable at work.

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 fifteen clients →

Then, whenever you want to know what to do next:

token_audit

One ranked queue: what is costing the most, priced per session and per month, each line naming how to fix it. Not a dashboard, not six reports — a queue.

The knowledge graph — the part nothing else has

Every agent session ends the same way: the reasoning evaporates. The next session re-derives it, at full price, forever.

This builds a living per-project graph — nodes for files, symbols, tasks and findings; edges for derived_from, contains, supersedes, contradicts, related — and it fills itself in from real work. No ingestion job, no embedding model, no rebuild step, no query to formulate.

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 burned tokens finding it out — and every other tool throws it away at the end of the session.

Why this is not RAG

Traversal plus lexical search: deterministic, instant, explainable, and it works offline.

The zero-turn refusal

A plain deny costs a full turn: the model calls Read, is refused, re-plans, calls smart_read. But at refusal time we already hold the file and the snapshot the graph stored — so the refusal carries the answer inside it. Nothing to re-plan, no second call. Turn cost drops from one to zero.

And when the graph already holds the verdict a tool output would support, the output never enters context at all. Not compressed. Absent.

The dashboard

npm run dashboard      # http://localhost:3100

Token balance Earned, spent and net — with the control-arm method stated up front rather than buried. When the experiment cannot yet support a headline figure, it says so.

Knowledge graph browser Focus view for one node and its neighbourhood; constellation view for the whole project. Click a finding to see what it was derived from, what superseded it, and what contradicts it.

Audit tab Contradictions, stale findings, and anything the graph believes that the code no longer supports — each with the diff that invalidated it.

One-click Markdown export Your agent's accumulated knowledge as documentation you can review, edit and commit. The graph stops being a black box the moment you can read it as prose.

Server-side by design: the browser asks for a neighbourhood, a search result or a page. A mature graph holds thousands of nodes, and shipping it wholesale would make every page load a multi-megabyte download for a view that shows twenty things.

What it does that other optimizers do not

Compaction is consolidation, not loss

Everyone else checkpoints and restores what you had — which spends the scarcest budget in the session replaying context you already paid for.

Selection here is derived, not a category list: cost-to-rederive × irrecoverability × reuse-probability, with dead ends and decisions on a floor, because cheap-to-find is not the same as cheap-to-find-again. Restoration then adapts to the situation — mid-problem, cold resume, or in-flow — within a measured budget:

Where you were: does clock skew explain the 401s? ruled out: token signing, clock drift on the client untested: NTP skew on the server

That is resuming a thought. A summary describes one.

Progressive disclosure that knows what you asked

A large tool result becomes a preview chosen by the session's actual question, after parsing the output's shape (test report, diff, stack trace, log, JSON) — not the first 40 lines because they are first.

[selected against: "which shard fails?"]
--- failures ---
  FAILED  DBNetTests.BceOnRelu -- expected 0.0 got NaN
  FAILED  TftGradientFlow -- gradient did not reach the encoder
---- omitted: 1,760 lines of passing tests (expand 8bb6bd66) ----

Every cut is named, because a model reasoning over a silent truncation cannot know it is missing anything. expand serves from a content-addressed store — it never re-runs your test suite — and expanding both teaches the next preview and promotes what you needed into the graph, so the second expansion never happens.

Prompt-cache economics, measured from your own transcript

A cache write costs 1.25× a plain token and a read costs 0.1×, so a prefix that keeps invalidating can cost more than every saving elsewhere. This reads the real numbers your client already recorded — then does the part a hit rate cannot:

! CLAUDE.md:2 has an embedded timestamp, invalidating everything after it
    about 329,421 tokens re-written per session

Attributed to a line, priced by what sits behind it. Keep-warm is decided by expected value from your observed gaps, per TTL tier — and when neither tier pays, it says so.

Model routing decided by outcomes, not by task size

Everyone guesses from task shape and never checks. This reads which model ran each episode and what happened — retries, errors, turns — and prices both mistakes: what an overpowered model wastes, and what an underpowered one costs in retries. A tier that needs a retry in more than half its episodes is excluded at any price, because four cheap turns that fail are not cheap.

Waste detection that becomes a ratchet

A report is read once and forgotten. Here a detection produces a durable, measured, reversible fix — a skip rule, a composite touch — plus a ~50-token session-start briefing so the waste never starts. Detectors are a shipped floor plus patterns derived from your project's own history, each carrying what it has actually saved:

generated/schema.d.ts: read in 9/9 sessions, never the source of a finding
    3,400 tokens/session (~$3.06/month); apply: waste_audit action="apply"

Anything that touches your files is proposed as a diff and never applied.

One audit across every project

fleet_audit ranks your whole machine by measured cost, and does something a per-project scanner cannot: a fix proven in one project is offered to the others containing the same file contents, carrying the evidence from where it was measured. Matching is by content hash, never by filename.

It also runs the natural experiment nobody else can — enforcing clients versus directive ones — and reports it whichever way it falls, with the confound stated.

Trust: we ship hooks that refuse your tool calls

That is a bigger ask than a normal dependency makes, so:

Verify the release. Published from CI with npm provenance — npm audit signatures ties the artifact to the workflow run and the commit, without trusting us. CHECKSUMS.sha256 ships alongs

…