Skip to content
Back to search

token-optimizer

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 12 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ooples/token-optimizer-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ooples/token-optimizer-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ooples--token-optimizer-mcp/badge.svg)](/listings/ooples--token-optimizer-mcp)

HTML

<a href="/listings/ooples--token-optimizer-mcp"><img src="/api/listings/ooples--token-optimizer-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**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/`](./src/integrations), and [docs/INSTALLATION.md](docs/INSTALLATION.md) walks through all sixteen.

<details> <summary><strong>Requirements and what happens without them</strong></summary>

- **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](docs/INSTALLATION.md#requirements-and-data).

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines
  1. {
  2. "name": "token-optimizer",
  3. "owner": {
  4. "name": "ooples",
  5. "url": "https://github.com/ooples"
  6. },
  7. "metadata": {
  8. "description": "Marketplace hosting the token-optimizer plugin for Claude Code.",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "token-optimizer",
  14. "source": "./src/plugin",
  15. "description": "Context-window optimization (caching, compression, smart file tooling) as an MCP server + usage skill + auto-optimization hooks."
  16. }
  17. ]
  18. }
README.md · README · 293 lines
  1. [![MCP Toplist](https://mcptoplist.com/badge/io.github.ooples%2Ftoken-optimizer-mcp.svg)](https://mcptoplist.com/server/io.github.ooples%2Ftoken-optimizer-mcp)
  2. <p align="center">
  3. <img src="docs/assets/logo-400.png" alt="Token Optimizer" width="96" height="96">
  4. </p>
  5. <h1 align="center">Token Optimizer MCP</h1>
  6. <p align="center">
  7. <strong>Cut what your AI coding agent costs without cutting what it gets done.</strong><br>
  8. Hooks, a proxy, and an MCP server for Claude Code, Codex, Copilot, Gemini and 12 more clients.
  9. </p>
  10. <p align="center">
  11. <a href="https://www.npmjs.com/package/@ooples/token-optimizer-mcp"><img src="https://img.shields.io/npm/v/%40ooples%2Ftoken-optimizer-mcp?logo=npm" alt="npm version"></a>
  12. <a href="https://www.npmjs.com/package/@ooples/token-optimizer-mcp"><img src="https://img.shields.io/npm/dm/%40ooples%2Ftoken-optimizer-mcp" alt="npm downloads"></a>
  13. <a href="https://github.com/ooples/token-optimizer-mcp/actions/workflows/ci.yml"><img src="https://github.com/ooples/token-optimizer-mcp/actions/workflows/ci.yml/badge.svg?branch=master" alt="CI"></a>
  14. <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
  15. <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22.14-339933?logo=node.js&logoColor=white" alt="Node.js 22.14+"></a>
  16. </p>
  17. <p align="center">
  18. <a href="#quick-start">Quick start</a> ·
  19. <a href="docs/HOW_IT_WORKS.md">How it works</a> ·
  20. <a href="docs/COMPARISON.md">Benchmarks</a> ·
  21. <a href="docs/INSTALLATION.md">All 16 clients</a> ·
  22. <a href="docs/REFERENCE.md">Reference</a> ·
  23. <a href="CHANGELOG.md">Changelog</a>
  24. </p>
  25. On SWE-bench Verified, Claude Code with the plugin in its default mode solved the
  26. same tasks as Claude Code without it, at **0.71× the cost** (7 of 7 resolved in
  27. both arms; across nine runs, 84 tasks resolved without the plugin and 83 with
  28. it). It gets there by stopping the waste agents make on their own: re-reading
  29. files that have not changed, dumping whole files to see three lines, unbounded
  30. searches, and re-deriving what an earlier session already worked out. Everything
  31. runs locally. No account, no hosted service, and telemetry is off unless you
  32. opt in twice.
  33. <p align="center">
  34. <img alt="Live Token Optimizer dashboard separating verified net MCP transport savings, excluded reports, per-agent attribution, and graph evidence" src="./docs/media/live/overview-live.png" width="1000">
  35. </p>
  36. <p align="center"><em>The local dashboard: one ledger for every agent, every saving, and what the optimizer itself cost.</em></p>
  37. ## Quick start
  38. **Claude Code.** Install the plugin rather than the bare MCP server: the plugin's
  39. hooks do the saving, while the server alone only offers tools the model can ignore.
  40. ```text
  41. /plugin marketplace add ooples/token-optimizer-mcp
  42. /plugin install token-optimizer@token-optimizer
  43. /reload-plugins
  44. ```
  45. You need Node.js 22.14 or later on Claude Code's PATH, and Claude Code 2.1.139 or
  46. later. Then check it works:
  47. ```bash
  48. npx token-optimizer-doctor
  49. ```
  50. The doctor feeds a synthetic payload to the real hook and confirms a large read is
  51. handled. Every failure names its own fix.
  52. **Codex, Copilot CLI, Gemini CLI, Cursor and the rest.** Every client runs the
  53. same server, `npx -y @ooples/token-optimizer-mcp@latest`. Ready-made configuration
  54. for each one is in [`src/integrations/`](./src/integrations), and
  55. [docs/INSTALLATION.md](docs/INSTALLATION.md) walks through all sixteen.
  56. <details>
  57. <summary><strong>Requirements and what happens without them</strong></summary>
  58. - **Node.js 22.14.0 or later**, for the hooks and the MCP server. `node` must be on
  59. the PATH of the client process. If you just installed Node.js or Git, start the
  60. client again from a new terminal so it picks up the new PATH.
  61. - **Claude Code 2.1.139 or later.** The hooks use the exec form
  62. (`"command": "node", "args": [...]`). An older Claude Code ignores `args`, so the
  63. hooks silently do nothing; the doctor reports it.
  64. - **If `node` cannot start**, the hooks let the tool call through
  65. (`"onFailure": "continue"`): you lose the savings, not the session. The MCP server
  66. shows as disconnected in `/mcp` until Node is reachable.
  67. Full details: [docs/INSTALLATION.md](docs/INSTALLATION.md#requirements-and-data).
  68. </details>
  69. ## Does it pay for itself?
  70. <p align="center">
  71. <img alt="Cost per SWE-bench task relative to the same agent without the plugin: assist (default) 0.71x, enforce 0.67x, advise 0.75x, off 1.00x; tasks resolved unchanged" src="./docs/assets/swebench-cost-by-mode.svg" width="900">
  72. </p>
  73. Each mode was run on the same 10 SWE-bench Verified instances, paired against a
  74. control session with no plugin. Resolution is graded by the official evaluator.
  75. `off` lands at 1.00×, which is what it should do: with the hooks and the proxy
  76. off, the product costs nothing extra and saves nothing.
  77. | Run (SWE-bench Verified, Claude Sonnet) | Instances | Cost vs. control | Resolved, control / plugin |
  78. | ----------------------------------------- | --------: | ---------------------- | -------------------------: |
  79. | Default mode (`assist`), first session | 10 | **0.705×** [0.63–0.80] | 7 / 7 |
  80. | Learned cost control, after the hoist fix | 15 | **0.634×** [0.54–0.74] | 14 / 14 (of 15) |
  81. | `off` (MCP server only) | 10 | 0.999× [0.83–1.20] | 7 / 7 |
  82. The samples are small and run-to-run variance is large, so read these as
  83. directions with intervals, not guarantees. The full method, every run including
  84. the ones where it lost, and the per-instance data are in
  85. [PR #559](https://github.com/ooples/token-optimizer-mcp/pull/559).
  86. **On compression alone**, against Alternative A's real implementation on its own
  87. fixtures, the proxy removes more of the payload on 15 of 18 workloads. Those
  88. tables are regenerated and checked by CI: see
  89. [docs/COMPARISON.md](docs/COMPARISON.md).
  90. ## What it does
  91. - **Stops the expensive call before it happens.** On clients with a
  92. pre-execution hook, an oversized `Read`, `Grep`, `cat` or `grep -r` is routed to
  93. a cached, bounded replacement, or refused outright in `enforce` mode. Re-reading a file you already read this
  94. session returns only the diff.
  95. - **Remembers what your agent worked out.** A per-project knowledge graph collects
  96. findings, decisions and dead ends as a side effect of normal work, and feeds them
  97. back when the agent touches the relevant file. Carrying a finding costs about 150
  98. tokens; re-deriving it costs 5k–50k.
  99. - **Compresses what it cannot avoid.** Tool output, logs, JSON and search results
  100. are compressed with the prompt cache in mind: providers bill a cached prefix at
  101. 0.1× and a rewritten one at 1.25×, so it optimizes the bill, not the byte count.
  102. - **Measures itself and says when it is losing.** Savings are recorded before and
  103. after, with later expansions debited from the same total, and attributed per
  104. client and per operation. Modeled savings are kept apart from measured ones.
  105. - **Works across 16 clients.** Ten can have wasteful calls refused; six get
  106. always-on routing rules where the host has no veto API.
  107. <details>
  108. <summary><strong>How it works: the four mechanisms</strong></summary>
  109. 1. **Hooks** sit in front of the client's built-in tools. In `enforce` mode a large
  110. read is denied with a message naming the cheaper call; in the default `assist`
  111. mode the hooks route, retrieve and capture without refusing anything.
  112. 2. **The proxy** sits between the client and the provider, compressing request
  113. bodies and keeping the cached prefix stable so cache reads stay cheap.
  114. 3. **The MCP server** provides `smart_read`, `smart_grep`, `smart_edit`,
  115. `optimize_text`, `token_audit` and the rest: diff-on-reread, bounded search,
  116. and an out-of-context store.
  117. 4. **The knowledge graph** is written by the hooks as the agent works and read
  118. back at the moment it is relevant.
  119. More: [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md).
  120. </details>
  121. <details>
  122. <summary><strong>The knowledge graph</strong></summary>
  123. ```
  124. you touch src/auth.ts
  125. │
  126. ├─ verify() compares exp against the LOCAL clock (finding, 0.9)
  127. ├─ per-host retry budgets; global was rejected — deadlock (decision)
  128. ├─ ! the skew fix was reverted once already (dead end)
  129. └─ [git] 47 changes in 90d, last three: "fix token expiry",
  130. "revert skew fix", "fix token expiry again"
  131. ```
  132. None of that is in your repository. It exists only because an agent once spent
  133. tokens finding it out, and it is gone at the end of the session unless something
  134. keeps it. No ingestion job, no embedding model, no rebuild step.
  135. More: [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md#the-knowledge-graph--the-part-nothing-else-has).
  136. </details>
  137. <details>
  138. <summary><strong>Modes: assist, enforce, advise, off</strong></summary>
  139. | Mode | What the hooks do |
  140. | ------------------ | --------------------------------------------------------- |
  141. | `assist` (default) | Route, retrieve, capture and compress; refuse nothing |
  142. | `enforce` | Also refuse large built-in reads and unbounded searches |
  143. | `advise` | Suggest the cheaper call without refusing |
  144. | `off` | Hooks and proxy off; the MCP server's tools still work |
  145. Set it with `TOKEN_OPTIMIZER_MODE`. The chart above shows what each mode cost on
  146. SWE-bench.
  147. </details>
  148. <details>
  149. <summary><strong>Supported clients</strong></summary>
  150. **Enforcing tier**: the client has a pre-execution hook, so a wasteful call can be
  151. refused.
  152. | Client | What installs |
  153. | ------------------ | ---------------------------------------------------------------------------------------------- |
  154. | Claude Code | Native plugin (see [Quick start](#quick-start)) |
  155. | Codex | Native plugin in [`src/integrations/codex/plugin`](./src/integrations/codex/plugin), or standalone hooks |
  156. | GitHub Copilot CLI | Project hooks in [`src/integrations/copilot`](./src/integrations/copilot) |
  157. | Gemini CLI | Gemini extension at the repository root |
  158. | Qwen Code | Extension bundle in [`src/integrations/qwen`](./src/integrations/qwen) |
  159. | Cursor | Project hooks and rule in [`src/integrations/cursor`](./src/integrations/cursor) |
  160. | Cline | Project hooks and rule in [`src/integrations/cline`](./src/integrations/cline) |
  161. | OpenCode | In-process plugin and hooks in [`src/integrations/opencode`](./src/integrations/opencode) |
  162. | Kilo | In-process plugin and hooks in [`src/integrations/kilo`](./src/integrations/kilo) |
  163. | Windsurf | Project hooks and rule in [`src/integrations/windsurf`](./src/integrations/windsurf) |
  164. **Rules tier**: Roo Code, Zed, Amp, Continue, Crush and Droid have no veto API, so
  165. they get always-on routing rules instead.
  166. Every config path is checked against the client's published documentation; see
  167. [docs/CLIENT_SUPPORT.md](docs/CLIENT_SUPPORT.md).
  168. </details>
  169. <details>
  170. <summary><strong>The dashboard</strong></summary>
  171. <p align="center">
  172. <img alt="Graph explorer in the live dashboard" src="./docs/media/live/graph-explorer-live.png" width="900">
  173. </p>
  174. The dashboard reads the local ledger: verified savings, excluded reports,
  175. per-agent attribution, hook health and the knowledge graph. It prices usage with
  176. the exact provider, model and rate tier it captured, and leaves an ambiguous model
  177. **Not priced** rather than guessing. More: [docs/DASHBOARD.md](docs/DASHBOARD.md).
  178. </details>
  179. <details>
  180. <summary><strong>Privacy and telemetry</strong></summary>
  181. - Nothing is measured about you unless you ask. Anonymous usage data takes two
  182. separate opt-ins: `TOKEN_OPTIMIZER_TELEMETRY=1` counts into a file on your own
  183. disk, and `TOKEN_OPTIMIZER_BEACON=1` is what uploads it. `DO_NOT_TRACK=1`
  184. overrides both.
  185. - An event can hold only numbers and flags. A string is dropped before it is
  186. written, so a path, prompt or error message cannot travel even by mistake. The
  187. machine identifier is a salted hash, never your hostname.
  188. - The version check runs only when you ask the doctor for a diagnosis, never
  189. during a session. `TOKEN_OPTIMIZER_UPDATE_CHECK=0` turns it off.
  190. - `npx token-optimizer-doctor` prints which of these is on and what has been
  191. recorded.
  192. Full details: [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md#the-30-second-version).
  193. </details>
  194. <details>
  195. <summary><strong>Verify the release, or remove it</strong></summary>
  196. Releases are published from CI with npm provenance, so
  197. `npm audit signatures` ties the package to the workflow run and the commit without
  198. trusting us. `CHECKSUMS.sha256` ships alongside for offline checking.
  199. To remove it, uninstall the plugin (`/plugin uninstall token-optimizer@token-optimizer`).
  200. For a hook install, `npx token-optimizer-uninstall` shows the plan and changes
  201. nothing; add `--apply` to carry it out. It removes only files that still match
  202. what it wrote, and names anything you have edited since. Step by step:
  203. [docs/INSTALLATION.md](docs/INSTALLATION.md#verify-it-check-it-remove-it).
  204. </details>
  205. ## Documentation
  206. | Page | What is in it |
  207. | ---------------------------------------------- | --------------------------------------------------------------------- |
  208. | [How it works](docs/HOW_IT_WORKS.md) | The mechanisms, subagents, the knowledge graph, trust and attribution |
  209. | [Benchmarks and comparison](docs/COMPARISON.md) | Head-to-head against Alternative A, what it does differently, where it loses |
  210. | [Installation](docs/INSTALLATION.md) | All sixteen clients, requirements, verification and removal |
  211. | [Reference](docs/REFERENCE.md) | Tools, compression statistics and the full technical reference |
  212. | [Dashboard](docs/DASHBOARD.md) | What the local dashboard shows |
  213. | [OrcaRouter](docs/ORCAROUTER.md) | Routing requests through OrcaRouter |
  214. | [Tool reference](docs/TOOLS.md) | Every MCP tool and its arguments |
  215. | [Token accounting](docs/TOKEN_ACCOUNTING.md) | How savings are counted and priced |
  216. ## Development
  217. ```bash
  218. git clone https://github.com/ooples/token-optimizer-mcp.git
  219. cd token-optimizer-mcp
  220. npm ci
  221. npm run build
  222. npm test
  223. ```
  224. The benchmarks, evaluation corpora and registry material live under
  225. [`bench/`](./bench). See [CONTRIBUTING](docs/CONTRIBUTING.md),
  226. [testing](docs/TESTING_INSTRUCTIONS.md) and the
  227. [security policy](.github/SECURITY.md).
  228. ## License
  229. MIT. See [LICENSE](./LICENSE). Commercial use is allowed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.