token-optimizer-mcp

Open source alternative to Tokenade

554 stars
MIT
Active this week
Last commit 3 days ago

Last verified Oct 19, 2026

Optimize token usage across AI coding agents by blocking redundant file reads, caching context, and building a persistent per-project knowledge graph.

Visit website GitHub554

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

Who token-optimizer-mcp is for#

Solo developers using Claude Code or Codex across long-running projects

Agents re-deriving architectural decisions, revisiting the same file repeatedly, and forgetting session conclusions are the primary cost drivers this tool targets. The knowledge graph captures those conclusions as a side effect of normal work, at about 150 tokens per finding versus the full re-derivation cost.

Skip if:

Your sessions are short and self-contained with no context carried between them. If each session starts fresh by design, graph delivery provides less value.

Teams maintaining multiple codebases with shared patterns

The cross-project graph scope pools findings from related repositories through opaque project IDs. When an agent working in one service touches a file pattern it has analyzed in a sibling service, relevant findings from that sibling are available without a separate lookup.

Skip if:

Your repositories have no meaningful shared patterns or architecture. Isolated codebases with unrelated domains see no cross-project benefit.

Developers measuring and reducing per-session AI costs

The dashboard tracks gross token reduction, net verified MCP transport savings, optional cost equivalents priced from provider receipts, and per-client attribution across all 16 supported clients. Each row shows what was avoided, what still reached the model, and what the graph cost to maintain.

Skip if:

Your primary goal is code generation quality, not context efficiency. Token Optimizer optimizes what reaches the model; it does not change the model's output behavior.

Engineering teams on corporate machines without external API access

The semantic harvest step can point at a local model endpoint, keeping all finding extraction on-machine with nothing sent externally. When no credential is configured, the server skips semantic harvest and uses the structural graph and derive-based findings, which require no outbound connection.

Skip if:

You are evaluating this for a managed cloud environment where installing local Node.js services or native CLI hooks is not permitted.

the problem

The problem it solves#

AI coding agents waste a disproportionate share of their context window on work they have already done. Reading an unchanged 200 KB file costs the full token load even when only three lines matter. Running an unbounded search returns thousands of results when one would do. And every session ends with all derived conclusions gone: the next session re-derives them from scratch, at full cost, every time.

The knowledge problem is separate from the file-reading problem. Even a well-tuned agent that avoids redundant reads still cannot remember what it worked out about a specific function three sessions ago. There is no place to store the finding "the skew fix was reverted once already" except in the active context, which gets summarized away. When the next agent session opens the same file, it starts over from zero.

how token-optimizer-mcp solves it

How it solves it#

Zero-turn file read refusal

When an agent calls Read on a file it already accessed this session, the request is intercepted and only the diff against the cached version is returned inside the refusal. The agent does not need a second round-trip to get the answer. Turn cost drops from one full file load to zero.

Per-project knowledge graph

Nodes for files, symbols, tasks, and findings accumulate from ordinary agent traffic with no ingestion job and no rebuild step. Edges encode derived_from, contains, supersedes, contradicts, and related relationships. Carrying a finding costs about 150 tokens; re-deriving the same finding costs 5,000 to 50,000 tokens.

Per-agent token attribution

A local dashboard at localhost:3100 breaks down tokens avoided, context returned, and cost equivalents by client identity. Codex, Claude Code, and Gemini get separate rows. Old records without identity stay explicitly unattributed rather than being folded into whichever client is currently open.

Support for 16 CLI clients

Native adapters cover Claude Code, Codex, Gemini CLI, and 13 other AI coding clients. The MCP server adds model-visible tools to any compliant client; native adapters add lifecycle hooks, automatic routing, and capture health reporting for clients whose protocol supports it.

Honest measurement, no manufactured savings

Gross token savings and deliberate expansions are tracked separately. Graph substitution estimates stay apart from verified MCP transport savings. The dashboard does not manufacture a savings estimate from missing data; rows without enough evidence say Not measured or Collecting explicitly.

No telemetry, fully local

The graph, the ledger, and the diagnostic logs stay on the local machine. No session content, file paths, or tool output leave the host. The semantic harvest step that extracts findings from agent work can point at a local model endpoint, keeping every step private and on-machine.

strengths · trade-offs

Strengths and trade-offs#

Strengths

Enforced at the tool layer, not advisoryThe file-read interception works at the plugin layer: the expensive call is blocked before the model makes it. Approaches that rely on the model choosing to call a smarter tool fail when the model is mid-task and ignoring system prompt instructions. Enforcement beats suggestion when the model is under pressure.
Carries verdicts, not raw evidenceThe knowledge graph stores derived conclusions, not raw file chunks. Classic retrieval-augmented approaches return evidence the model must still interpret at full cost. Token Optimizer delivers the finished reasoning at about 150 tokens per finding, versus the 5,000 to 50,000 tokens it cost to produce originally.
MIT license, commercial use allowedMIT means you can run it at work, include it in internal tooling, and modify it without restriction. No fair-code or source-available terms govern what you can do with your deployment. The README confirms commercial use is allowed.
Staleness is computed, not hiddenWhen a graph finding is outdated, the system delivers it with the invalidating diff rather than serving the stale version silently. Content hashes drive invalidation. A finding that no longer applies is surfaced with the reason, not served as if it were still current.

Trade-offs

-Node.js 22 or later requiredThe server requires Node.js 22 or later. Projects on older Node versions or environments that already pin a different Node version need to verify compatibility before adding the server to their tool chain.
-Knowledge graph starts emptyThe graph accumulates from real agent traffic, not from a batch ingest of your codebase. Coverage follows attention: files the agent has never touched have no graph data, and new repositories need several sessions before graph delivery meaningfully reduces re-derivation costs.
-Semantic harvest requires a model credential or local endpointThe model-based finding extraction path requires either an external API key or a locally running model endpoint. Without one it reports off:no-key and skips that path. The structural graph and derive-based findings still work without a credential, but semantic harvest coverage is absent until a model is configured.

versus alternatives

token-optimizer-mcp vs alternatives#

Token Optimizer MCP vs Letta

Letta (formerly MemGPT) is a managed cloud service for persistent agent memory. Token Optimizer MCP solves an adjacent problem through a different mechanism and runs entirely on local infrastructure rather than a hosted service.

Feature	Token Optimizer MCP	Letta (managed)
License	MIT	Proprietary
Deployment	Local, self-hosted	Managed cloud
Memory model	Knowledge graph (verdicts and traversal)	Virtual context (paging and archival)
Token accounting	Per-agent dashboard, measured	Not a product feature
Client support	16 CLI coding clients	API-based agents
Telemetry	None	Cloud service
Cost	Free	Paid above free tier

Token Optimizer MCP is the better choice for developers using CLI coding agents who want context optimization to run entirely locally. The tool intercepts operations at the plugin layer, blocking the expensive read before it happens. The knowledge graph stores verdicts (derived conclusions) rather than paged-in memories, so the agent receives finished reasoning at about 150 tokens per finding rather than raw evidence it must re-interpret at full cost.

Letta's managed cloud is the better fit when you need a hosted memory layer with no infrastructure to maintain, or when you are building custom agent pipelines via API rather than using CLI coding tools. Its paging and archival model handles very long agent conversations in ways that Token Optimizer MCP, focused on session-level coding tool optimization, does not address.

install · quick start

Quick start#

bash

Install via npm to set up the token accounting server.
```bash
npm install @ooples/token-optimizer-mcp
```

tech stack · detected from GitHub

What it's built on#

Languages: JavaScriptPythonTypeScript
Frameworks: Express

frequently asked

FAQ#

How does Token Optimizer MCP block redundant file reads?

When an agent calls Read on a file it already accessed this session, the plugin intercepts the call and returns only the diff against the cached version inside the refusal message. The full file never enters context. The agent does not need a second call because the diff arrives inside the refusal itself, dropping the turn cost to zero.

Does the knowledge graph send data to any external service?

No. The graph, ledger, and logs stay on the local machine. The semantic harvest step reports off:no-key when no credential is configured and skips entirely. Pointing it at a local model endpoint keeps every step on-machine with nothing sent externally at any stage.

How is the knowledge graph different from RAG?

Classic retrieval-augmented approaches retrieve evidence; the model re-derives meaning each time. The knowledge graph retrieves verdicts: the reasoning already happened, so the agent receives the finished conclusion rather than the raw content it was derived from. Retrieval uses graph traversal from the file being touched, not similarity search. Staleness is computed from content hashes rather than served silently.

How long does it take to build a useful knowledge graph?

The structural graph (files, symbols, tasks, and the edges between them) starts accumulating from the first session with no configuration. Finding coverage follows attention: files the agent has touched several times build up findings faster than untouched files. New repositories need several sessions before graph delivery meaningfully reduces re-derivation costs.

Does Token Optimizer MCP work with AI clients other than Claude Code?

Yes. Sixteen CLI clients are supported, including Codex and Gemini CLI. The MCP server adds model-visible tools to any compliant client; native adapters add lifecycle hooks and per-client attribution for clients whose protocol supports them. Clients without native hook support get MCP tools but not automatic routing or capture health reporting.

also worth a look

Similar open-source tools#

magic-compact

Alternative toTokenade

Lossless context compression for Claude Code and OpenCode

173 GitHub stars
Licence BSD-3-Clause

context-mode

Alternative toTokenade

Cuts LLM context use by up to 98% per session via local MCP sandbox

31,315 GitHub stars
Licence Elastic License 2.0 (ELv2)

rtk

Alternative toTokenade

CLI proxy that removes 89% of agent context noise on average

84,082 GitHub stars
Licence Apache-2.0

Caveman

Alternative toTokenade

Token-slashing caveman-speak for cheaper, faster AI code.

113,757 GitHub stars
Licence Apache-2.0

Hermes Agent

Featured

Alternative toGrok Bot

Self-hosted AI agent: persistent memory, multi-channel chat, model choice.

255,514 GitHub stars
Licence MIT

Vllm

Alternative toTogether AI

High-throughput LLM inference server with OpenAI-compatible API

94,441 GitHub stars
Licence Apache-2.0

by category

Open source tools in these categories#

404

2,957 GitHub stars
Licence Apache-2.0
#AI Agents

Inbox Zero

Alternative toSuperhuman

AI email assistant that drafts replies and clears your inbox

12,712 GitHub stars
Licence AGPL-3.0
#Email

rakazo

Alternative toGrok Bot

AI teammates you own: your keys, your model, your machine.

4,904 GitHub stars
Licence Apache-2.0
#AI Agents

Feature your project

The projects we add and every new guide. Free, unsubscribe any time.

Find open source alternatives to paid software

Token Optimizer MCP vs Letta

Feature	Token Optimizer MCP	Letta (managed)
License	MIT	Proprietary
Deployment	Local, self-hosted	Managed cloud
Memory model	Knowledge graph (verdicts and traversal)	Virtual context (paging and archival)
Token accounting	Per-agent dashboard, measured	Not a product feature
Client support	16 CLI coding clients	API-based agents
Telemetry	None	Cloud service
Cost	Free	Paid above free tier

Who token-optimizer-mcp is for#

Solo developers using Claude Code or Codex across long-running projects

Skip if:

Teams maintaining multiple codebases with shared patterns

Skip if:

Developers measuring and reducing per-session AI costs

Skip if:

Engineering teams on corporate machines without external API access

Skip if:

The problem it solves#

How it solves it#

Zero-turn file read refusal

Per-project knowledge graph

Per-agent token attribution

Support for 16 CLI clients

Honest measurement, no manufactured savings

No telemetry, fully local

Strengths and trade-offs#

Strengths

Trade-offs

token-optimizer-mcp vs alternatives#

Token Optimizer MCP vs Letta

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

AI & Machine Learning

Developer Tools

LLMOps & AI Tooling

Find open source alternatives to paid software

Who token-optimizer-mcp is for#

Solo developers using Claude Code or Codex across long-running projects

Skip if:

Teams maintaining multiple codebases with shared patterns

Skip if:

Developers measuring and reducing per-session AI costs

Skip if:

Engineering teams on corporate machines without external API access

Skip if:

The problem it solves#

How it solves it#

Zero-turn file read refusal

Per-project knowledge graph

Per-agent token attribution

Support for 16 CLI clients

Honest measurement, no manufactured savings

No telemetry, fully local

Strengths and trade-offs#

Strengths

Trade-offs

token-optimizer-mcp vs alternatives#

Token Optimizer MCP vs Letta

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

AI & Machine Learning

Developer Tools

LLMOps & AI Tooling

Find open source alternatives to paid software