Skip to content
Back to search

tokeneconomizer

MarketplaceWorks with Claude CodeGitHub

TokenEconomizer: experience-driven black-box cost control for coding agents.

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 11 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/microsoft/TokenEconomizer 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/microsoft/TokenEconomizer'

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/microsoft--tokeneconomizer/badge.svg)](/listings/microsoft--tokeneconomizer)

HTML

<a href="/listings/microsoft--tokeneconomizer"><img src="/api/listings/microsoft--tokeneconomizer/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

You need one of these agents, signed in any way it supports, and Python 3.10 or newer on `PATH`. The plugin needs no API key of its own and never handles credentials, so any plan or login works.

Install

Run these commands in the folder where you want to keep the clone. Claude Code, Codex, the Copilot CLI and opencode run the plugin from the clone, so leave it in place. Then start the agent in one of your repositories.

**Claude Code**

git clone https://github.com/microsoft/TokenEconomizer.git
claude plugin marketplace add "$PWD/TokenEconomizer"
claude plugin install tokeneconomizer@tokeneconomizer

Start `claude`, trust the folder (**Yes, I trust this folder**), and run `/tokeneconomizer:status`, allowing its script if asked. Once per machine, and again after Claude Code updates, run `/tokeneconomizer:toolprune refresh-catalog`.

**Codex**

git clone https://github.com/microsoft/TokenEconomizer.git
codex plugin marketplace add "$PWD/TokenEconomizer"
codex plugin add tokeneconomizer@tokeneconomizer

Start `codex`, choose **Trust and continue** for the folder, then at **Hooks need review** choose **Trust all and continue**. The hooks take effect from your next Codex session, so quit (`/exit`), start `codex` again, and check with `$tokeneconomizer:status`.

**Copilot CLI**

git clone https://github.com/microsoft/TokenEconomizer.git
copilot plugin marketplace add "$PWD/TokenEconomizer"
copilot plugin install tokeneconomizer@tokeneconomizer

Start `copilot`, choose **Yes, and remember this folder for future sessions**, and run `/tokeneconomizer:status`, choosing **Yes** to run its script. Once per machine, and again after Copilot updates, run `/tokeneconomizer:toolprune refresh-catalog`.

**Pi**

pi install git:github.com/microsoft/TokenEconomizer

Start `pi` and run `/te status`.

**Cursor Agent** (experimental)

python scripts/build_plugin.py --out ~/.cursor/plugins/local/

Reload Cursor, confirm `tokeneconomizer` appears in Customize, then send a prompt in a repository. Check its state from a terminal with `~/.tokeneconomizer/bin/te --host cursor status`. Cursor's published hooks provide session, prompt, tool-result and completion events. Its transcript format and per-session token usage are not a supported public interface, so the adapter records needed hook events locally and reports session cost as unavailable. Cursor support is macOS and Linux only: on Windows, Cursor runs hook commands through PowerShell, and this plugin's launcher is a POSIX shell script.

**opencode** (experimental)

git clone https://github.com/microsoft/TokenEconomizer.git
mkdir -p ~/.config/opencode/plugins
ln -s "$PWD/TokenEconomizer/plugin/opencode/tokeneconomizer.ts" ~/.config/opencode/plugins/

Start `opencode` and send a prompt, then check in the repository with `~/.tokeneconomizer/bin/te --host opencode status`. opencode has no plugin commands, so the plugin's commands run from a terminal.

**Hermes Agent** (experimental; micro-skills and the loop guard, on the classic CLI and one-shot runs)

git clone https://github.com/microsoft/TokenEconomizer.git
ln -s "$PWD/TokenEconomizer/plugin/hermes" ~/.hermes/plugins/tokeneconomizer
hermes plugins enable tokeneconomizer
hermes gateway restart

Link it rather than running `hermes plugins install`, which leaves the launchers behind when given this directory and refuses the whole repository at its security scan. Send a prompt, then check in the repository with `~/.tokeneconomizer/bin/te --host hermes status`.

If the install worked, the status command prints a short status block. `refresh-catalog` records every tool a session loads (without a model call), so that tool pruning can consider all of them. Keep the marketplace path absolute, as above: the Copilot CLI reads a relative path such as `./TokenEconomizer` as the name of a GitHub repository.

To update:

| Agent | Update | |---|---|

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 · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "tokeneconomizer",
  3. "owner": {
  4. "name": "TokenEconomizer authors"
  5. },
  6. "description": "TokenEconomizer: experience-driven black-box cost control for coding agents.",
  7. "plugins": [
  8. {
  9. "name": "tokeneconomizer",
  10. "source": "./plugin",
  11. "description": "Micro-skills learned per repository, tool pruning of tools a repository never uses (one command gives them back), and a failure-loop guard."
  12. }
  13. ]
  14. }
README.md · README · 543 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # TokenEconomizer: Experience-Driven Black-Box Cost Control for Coding Agents
  2. <p align="center">
  3. Aaron J. Li<sup>1</sup>,
  4. Weijia Xu<sup>2</sup>,
  5. Chandan Singh<sup>2</sup>,
  6. Zixiao Chen<sup>3</sup>,
  7. Jeevana Priya Inala<sup>2</sup>,
  8. Charlotte Siska<sup>3</sup>,
  9. <br>
  10. Acar Tamersoy<sup>3</sup>,
  11. Bin Yu<sup>1</sup>,
  12. Ion Stoica<sup>1</sup>,
  13. Michel Galley<sup>2</sup>,
  14. Jianfeng Gao<sup>2</sup>
  15. </p>
  16. <p align="center">
  17. <sup>1</sup>UC Berkeley &nbsp; <sup>2</sup>Microsoft Research &nbsp; <sup>3</sup>Microsoft Security
  18. </p>
  19. <p align="center">
  20. <a href="https://arxiv.org/abs/2610.22732"><img src="https://img.shields.io/badge/arXiv-2610.22732-b31b1b.svg" alt="arXiv"></a>
  21. <a href="https://tokeneconomizer.github.io"><img src="https://img.shields.io/badge/project-page-2f6fb0.svg" alt="Project page"></a>
  22. <a href="https://x.com/aaron_jli/status/2114797313613053952"><img src="https://img.shields.io/badge/X-post-000000.svg?logo=x&logoColor=white" alt="X post"></a>
  23. <img src="https://img.shields.io/badge/python-3.10%2B-3776ab.svg" alt="Python 3.10+">
  24. <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license">
  25. </p>
  26. <p align="center">
  27. <a href="https://trendshift.io/repositories/315380"><img src="https://trendshift.io/api/badge/trendshift/repositories/315380/daily?language=Python" alt="#1 Python repository of the day on Trendshift" width="250" height="55"></a>
  28. <a href="https://trendshift.io/repositories/315380"><img src="https://trendshift.io/api/badge/trendshift/repositories/315380/weekly?language=Python" alt="#10 Python repository of the week on Trendshift" width="250" height="55"></a>
  29. </p>
  30. <p align="center">
  31. Our measurement on SWE-Bench tasks: <b>18.4–30.9% lower mean cost</b> across five agent–model
  32. combinations, cheaper in <b>all 30</b> repository × combination cells, and Pass@1 up in
  33. <b>4 of 5</b>. <a href="#results">Results</a>
  34. </p>
  35. <p align="center">
  36. <picture>
  37. <source media="(prefers-reduced-motion: reduce)" srcset="docs/assets/teaser.png">
  38. <img src="docs/assets/teaser.gif" width="100%" alt="An animation that opens on a title card: TokenEconomizer, experience-driven black-box cost control for coding agents, with its three mechanisms (micro-skills, tool pruning, failure-loop intervention), the agents it works with (Claude Code, Codex, GitHub Copilot CLI, Pi) and the UC Berkeley and Microsoft logos. Then a schematic of six sessions in one repository, each a bar of what it cost: the work itself plus three kinds of waste, namely re-learning the repo, tools never used, and getting stuck in loops. Each of the first three sessions teaches TokenEconomizer one thing, in order: 1 micro-skills remember how the repo works (run tests with python -m pytest), 2 tool pruning skips tools never used here (Read and Edit kept, Notebook and Browser left out), and 3 failure-loop intervention spots loops and steps in (the same error three times meets a nudge to try another way). In the session after each lesson that waste shrinks, so the bars step down below a dashed line marking the cost without TokenEconomizer. It ends on results measured on SWE-Bench tasks: 18.4–30.9% lower mean cost across five agent–model combinations, cheaper than default in 30 of 30 repository × combination cells, and Pass@1 up in 4 of 5; per combination, cost 23.6% lower and Pass@1 +1.3 for Claude Code with Sonnet 5, 30.9% and −1.0 with Opus 4.8, 24.7% and +0.9 for Codex with GPT-5.6 Terra, 26.1% and +1.6 with GPT-5.6 Sol, and 18.4% and +2.6 for Copilot CLI with Sonnet 5.">
  39. </picture>
  40. </p>
  41. TokenEconomizer makes coding agents cheaper to run in the repositories you work in often,
  42. without changing the agent itself. It learns from the sessions an agent has already run in a
  43. repository, and uses that experience to cut waste in the sessions that follow. It has three
  44. mechanisms:
  45. - **Micro-skills: remember how the repository works.** Sessions keep rediscovering the same
  46. facts: a build step that must run first, the spelling of a command that works here
  47. (`python -m pytest` where `pytest` is missing, `npx tsc` where `tsc` is), an environment
  48. variable a command needs, where generated files live. Micro-skills learns such facts, in any
  49. language, from two sources: failures that repeat across sessions, and a model that reviews the
  50. recent sessions every *k* sessions (*k* = 3) and proposes facts. A fact is stated at the start
  51. of each session once three sessions have confirmed it, and dropped when later sessions
  52. contradict it.
  53. - **Tool pruning: stop loading tools that go unused.** Every loaded tool's definition is sent with
  54. every request. A tool that goes unused over *p* prompts spread across at least *m* sessions, or
  55. over *s* sessions of any length (*p* = 10, *m* = 2, *s* = 5), is left out of the next sessions
  56. through the agent's own settings. One command brings it back.
  57. - **Failure-loop intervention (the loop guard): step in when a turn is stuck.** When a turn (the
  58. agent's work on one prompt) keeps hitting the same failures, a judge model checks whether it is
  59. stuck. If the judge is at least *c* sure (*c* = 0.7), the agent gets a redirect (a short note,
  60. added to its context, to try another approach), at most *r* times per turn (*r* = 1). If the
  61. turn is still stuck after that, TokenEconomizer tells you how to stop it; it never stops a turn
  62. itself.
  63. TokenEconomizer is a plugin for **Claude Code**, **Codex**, the **GitHub Copilot CLI** and **Pi**,
  64. with experimental support for **opencode**, **Cursor Agent**, **Grok Build**, **Hermes Agent**,
  65. the **Antigravity CLI** and **Factory Droid**. Each italic
  66. letter above is a setting, shown with its default ([Settings](#settings)), and each mechanism can be turned on or
  67. off. The plugin announces each action in one line, and if any part of it fails, your session
  68. carries on as if it were not installed. Its model calls (the fact proposer, and the judge with the
  69. redirect it writes) run through your own agent, on the same plan or login, and their cost is
  70. included in its reports. What it learns stays on your machine, in `~/.tokeneconomizer`.
  71. ## Results
  72. The paper ran five agent–model combinations on the same 277 SWE-Bench tasks from six repositories.
  73. Each task ran as its own session, and each repository's tasks ran in order, starting with nothing
  74. learned. Costs include every model call TokenEconomizer made. Within each repository and
  75. combination, cost fell by 5–40%. The savings held on Web-Bench (16–21% lower) and on two
  76. security-auditing benchmarks where every task is in a new repository (6–20% lower). The
  77. [project page](https://tokeneconomizer.github.io) has interactive charts, per-repository numbers
  78. and nine annotated runs, and [`experiments/`](experiments/README.md) reruns the SWE-Bench and
  79. Web-Bench experiments.
  80. ## How it works
  81. <p align="center"><img src="docs/assets/framework_overview.png" width="100%" alt="TokenEconomizer: the plugin keeps what it knows about a repository and applies micro-skills, tool pruning and failure-loop intervention to your unchanged coding agent; each finished session's log updates all three"></p>
  82. Coding agents are built to finish tasks, not to keep them cheap. Every turn pays again for the
  83. agent's instructions, every loaded tool, and the conversation so far. Developers use the same
  84. agent on the same repository again and again, so much of that cost repeats: the same facts
  85. rediscovered, the same unused tools sent, the same kinds of failing loops. TokenEconomizer leaves
  86. the agent's model, weights and code alone and learns across a repository's sessions instead of
  87. treating each one on its own, so whatever the plugin spends is paid back over the sessions that
  88. follow. Four principles guide the mechanisms:
  89. - **Work through what the agent already reads.** Facts enter the context at session start, and
  90. tools are removed through the agent's own settings, so nothing depends on the agent learning a
  91. new tool.
  92. - **Count cost as it is billed.** Most tokens in a session are cached re-reads, so cost is
  93. computed with cache pricing, and it includes the plugin's own model calls.
  94. - **Protect task success.** Facts form only from repeated evidence, tools are removed only after
  95. going unused, and the loop guard leaves alone a turn that is still making progress.
  96. - **Keep every action reversible.** A fact that later sessions contradict is dropped, removed
  97. tools can be given back, and the loop guard only redirects and tells you: stopping a turn is
  98. your call.
  99. ## Quick start
  100. You need one of these agents, signed in any way it supports, and Python 3.10 or newer on
  101. `PATH`. The plugin needs no API key of its own and never handles credentials, so any plan or
  102. login works.
  103. ### Install
  104. Run these commands in the folder where you want to keep the clone. Claude Code, Codex, the
  105. Copilot CLI and opencode run the plugin from the clone, so leave it in place. Then start the agent
  106. in one of your repositories.
  107. **Claude Code**
  108. ```sh
  109. git clone https://github.com/microsoft/TokenEconomizer.git
  110. claude plugin marketplace add "$PWD/TokenEconomizer"
  111. claude plugin install tokeneconomizer@tokeneconomizer
  112. ```
  113. Start `claude`, trust the folder (**Yes, I trust this folder**), and run
  114. `/tokeneconomizer:status`, allowing its script if asked. Once per machine, and again after Claude
  115. Code updates, run `/tokeneconomizer:toolprune refresh-catalog`.
  116. **Codex**
  117. ```sh
  118. git clone https://github.com/microsoft/TokenEconomizer.git
  119. codex plugin marketplace add "$PWD/TokenEconomizer"
  120. codex plugin add tokeneconomizer@tokeneconomizer
  121. ```
  122. Start `codex`, choose **Trust and continue** for the folder, then at **Hooks need review**
  123. choose **Trust all and continue**. The hooks take effect from your next Codex session, so quit
  124. (`/exit`), start `codex` again, and check with `$tokeneconomizer:status`.
  125. **GitHub Copilot in VS Code**
  126. See [VS Code setup](plugin/README.md#github-copilot-in-vs-code) to install from the editor
  127. with the **Copilot** session target, without GitHub CLI or standalone Copilot CLI.
  128. **Copilot CLI**
  129. ```sh
  130. git clone https://github.com/microsoft/TokenEconomizer.git
  131. copilot plugin marketplace add "$PWD/TokenEconomizer"
  132. copilot plugin install tokeneconomizer@tokeneconomizer
  133. ```
  134. Start `copilot`, choose **Yes, and remember this folder for future sessions**, and run
  135. `/tokeneconomizer:status`, choosing **Yes** to run its script. Once per machine, and again after
  136. Copilot updates, run `/tokeneconomizer:toolprune refresh-catalog`.
  137. **Pi**
  138. ```sh
  139. pi install git:github.com/microsoft/TokenEconomizer
  140. ```
  141. Start `pi` and run `/te status`.
  142. **Factory Droid** (experimental; micro-skills, the loop guard and session cost, not tool pruning)
  143. ```sh
  144. git clone https://github.com/microsoft/TokenEconomizer.git
  145. cd TokenEconomizer
  146. python scripts/build_plugin.py --droid
  147. droid plugin marketplace add "$PWD/dist/tokeneconomizer-droid"
  148. droid plugin install tokeneconomizer@tokeneconomizer-droid --scope user
  149. ```
  150. Start a new Droid session (its hooks are snapshotted at startup) and run
  151. `/tokeneconomizer-status`. Droid keeps each session's token usage in a settings file beside its
  152. log, so folded sessions are priced like any other host's. Its TUI has no persistent per-tool
  153. setting, so tool pruning stays off; and because `droid exec` writes a session log of its own,
  154. micro-skills' paid proposer and the loop guard's judge stay off until `droid_sidecall` is on
  155. (when on, they may use only Droid's read-only `Read` tool).
  156. See **[`docs/DROID.md`](docs/DROID.md)** for what works and how to import earlier sessions.
  157. **Cursor Agent** (experimental)
  158. ```sh
  159. python scripts/build_plugin.py --out ~/.cursor/plugins/local/
  160. ```
  161. Reload Cursor, confirm `tokeneconomizer` appears in Customize, then send a prompt in a repository.
  162. Check its state from a terminal with `~/.tokeneconomizer/bin/te --host cursor status`. Cursor's
  163. published hooks provide session, prompt, tool-result and completion events. Its transcript format
  164. and per-session token usage are not a supported public interface, so the adapter records needed
  165. hook events locally and reports session cost as unavailable. Cursor support is macOS and Linux
  166. only: on Windows, Cursor runs hook commands through PowerShell, and this plugin's launcher is a
  167. POSIX shell script.
  168. **Grok Build** (experimental)
  169. ```sh
  170. git clone https://github.com/microsoft/TokenEconomizer.git
  171. grok plugin marketplace add "$PWD/TokenEconomizer"
  172. grok plugin install tokeneconomizer --trust
  173. ```
  174. Grok runs Claude Code plugins, so this is the Claude Code plugin: grok loads `plugin/hooks/hooks.json`
  175. and TokenEconomizer recognises the grok session in the hook payload. (If you already installed it
  176. for Claude Code, grok reads `~/.claude/plugins` and runs it in your sessions; this version reads
  177. those as grok sessions.) Micro-skills and the loop guard only; tool pruning is not available.
  178. Confirm `tokeneconomizer` is enabled in `grok plugin list`, start `grok`, and check with
  179. `~/.tokeneconomizer/bin/te --host grok status`.
  180. The learned facts arrive with the session's first tool call, not at its start
  181. ([its limits](plugin/README.md#grok-build)).
  182. **Antigravity CLI** (`agy`; experimental; micro-skills' LLM-free facts only)
  183. ```sh
  184. python scripts/build_plugin.py --out dist/marketplace
  185. agy plugin install dist/marketplace/tokeneconomizer
  186. ```
  187. Start `agy` and send a prompt in a repository, then check with
  188. `~/.tokeneconomizer/bin/te --host antigravity status` (on Windows, `<plugin>\scripts\te.cmd --host antigravity status`, run in the repository; `<plugin>` is the folder above `scripts\te_bootstrap.py` in `%USERPROFILE%\.tokeneconomizer\bin\te.json`, which the first session writes). `agy` has no plugin commands, so the
  189. plugin's commands run from a terminal. The plugin makes no model call through `agy`, which has no
  190. option that runs a prompt with every tool off, so the paid proposer and the loop guard are off
  191. and tool pruning is not available. Works across Windows, macOS, and Linux with native Windows batch launchers (`scripts\te-hook.cmd`, `scripts\te.cmd`). Tested on `agy` 1.5.1 and 1.5.2 on Windows 11, macOS, and Linux.
  192. See [its limits](plugin/README.md#antigravity-cli).
  193. **opencode** (experimental)
  194. ```sh
  195. git clone https://github.com/microsoft/TokenEconomizer.git
  196. mkdir -p ~/.config/opencode/plugins
  197. ln -s "$PWD/TokenEconomizer/plugin/opencode/tokeneconomizer.ts" ~/.config/opencode/plugins/
  198. ```
  199. The one file serves both generations: opencode 1.x reads its `server` entry, 2.x its `setup`.
  200. Start `opencode` and send a prompt, then check in the repository with
  201. `~/.tokeneconomizer/bin/te --host opencode status`. opencode has no plugin commands, so the
  202. plugin's commands run from a terminal.
  203. **Hermes Agent** (experimental; micro-skills and the loop guard, on the classic CLI and one-shot
  204. runs)
  205. ```sh
  206. git clone https://github.com/microsoft/TokenEconomizer.git
  207. ln -s "$PWD/TokenEconomizer/plugin/hermes" ~/.hermes/plugins/tokeneconomizer
  208. hermes plugins enable tokeneconomizer
  209. hermes gateway restart
  210. ```
  211. Link it rather than running `hermes plugins install`, which leaves the launchers behind when given
  212. this directory and refuses the whole repository at its security scan. Send a prompt, then check in the repository with `~/.tokeneconomizer/bin/te --host hermes status`.
  213. If the install worked, the status command prints a short status block. `refresh-catalog`
  214. records every tool a session loads (without a model call), so that tool pruning can consider all
  215. of them. Keep the marketplace path absolute, as above: the Copilot CLI reads a relative path such
  216. as `./TokenEconomizer` as the name of a GitHub repository.
  217. To update:
  218. | Agent | Update |
  219. |---|---|
  220. | Claude Code, Copilot CLI, opencode | `git pull` in the clone |
  221. | Factory Droid | `git pull` in the clone, then the `build_plugin.py --droid` and install lines again |
  222. | Hermes Agent | `git pull` in the clone, then `hermes gateway restart` |
  223. | Antigravity CLI | build the bundle again and `agy plugin install` it |
  224. | Codex | `git pull` in the clone, then the `codex plugin add` line again |
  225. | Pi | `pi update --extensions` |
  226. **[`plugin/README.md`](plugin/README.md)** walks through each agent in more detail, including
  227. uninstalling, using Copilot with your own model key, and troubleshooting.
  228. ### Supported versions
  229. | Agent | Supported | Older versions |
  230. |---|---|---|
  231. | Claude Code | 2.1.300 to 2.1.310 | not supported |
  232. | Codex | 0.153.1 to 0.164.0 | not supported |
  233. | Copilot CLI | 1.0.83 to 1.0.102 | not supported |
  234. | Pi | 1.2.0 to 1.3.0 | 0.99.x: load the extension by path (below) |
  235. | Cursor Agent (experimental) | 3.24.9 and cursor-agent 2026.11.05, macOS and Linux (below) | not tested |
  236. | Grok Build (experimental) | 1.0.70 | not tested |
  237. | opencode (experimental) | 1.19.5 and 2.2.0 | not tested |
  238. | Hermes Agent (experimental) | 0.22.5 | not tested |
  239. | Antigravity CLI (experimental) | agy 1.5.1 and 1.5.2, Windows 11, macOS and Linux | not tested |
  240. | Factory Droid (experimental) | 0.233.0, macOS (below) | not tested |
  241. The commands above were tested on the oldest and newest version in each range; newer versions
  242. have not been tested yet.
  243. - **Codex before 0.141.0** does not run plugin hooks at all.
  244. - **Pi 0.99.x**: instead of `pi install`, clone the repository and start each session with
  245. `pi --extension /path/to/TokenEconomizer/plugin/pi/tokeneconomizer.ts`, using your clone's
  246. full path; `git pull` in the clone updates it.
  247. - **opencode** support is experimental: it was tested on 1.19.5 and 2.2.0 only, and not in the
  248. 2.x terminal UI.
  249. - **Cursor Agent** support is experimental. Cursor 3.24.9 loaded the local plugin. On
  250. `cursor-agent` 2026.11.05, `cursor-agent --trust -p` delivered `sessionStart`, `postToolUse`,
  251. `afterShellExecution` and `sessionEnd`, but not `beforeSubmitPrompt` or `stop`; context returned
  252. from `sessionStart` and `postToolUse` reached the model. Prompts are then counted from Cursor's
  253. own transcript and a run that ends as completed closes its turn. Session usage stays unavailable,
  254. and the interactive TUI has not been tested.
  255. - **Grok Build** support is experimental: it was verified on 1.0.70 only, against its documented
  256. hook contract and live hook payloads. Learned facts reach the model with the session's first tool
  257. call, and tool pruning is not available. See [its limits](plugin/README.md#grok-build).
  258. - **Antigravity CLI** support is experimental: it was tested against agy 1.5.1 and 1.5.2 on Windows 11,
  259. macOS, and Linux. It was written against agy's hook contract and transcript format, which are not a
  260. public interface, and only micro-skills' LLM-free facts are supported: the plugin makes no model call
  261. through `agy`. See [its limits](plugin/README.md#antigravity-cli).
  262. - **Hermes Agent** support is experimental: it was tested on 0.22.5 only, with a scripted local
  263. model and one free real model, on the classic CLI and one-shot runs only. Micro-skills and a
  264. redirect reaching a real model are verified there; the still-stuck notice reaching a person is
  265. not. Its other surfaces (the Ink TUI, the Desktop app, messaging platforms, cron) and
  266. subagents are ignored, and tool pruning is not available. See
  267. [its limits](plugin/README.md#hermes-agent).
  268. - **Factory Droid** support is experimental: it was tested on 0.233.0 only, on macOS. Droid
  269. documents the hook contract this adapter uses, and the plugin's own hook output is covered by
  270. tests; a learned fact reaching a live Droid model was verified on 2026-11-05 (a new session
  271. received the 793-character block as `hookSpecificOutput.additionalContext` and the model
  272. repeated it). Droid's TUI has no persistent per-tool setting (Factory issue #65), so tool
  273. pruning is not available; its session logs are read for micro-skills and the loop guard, and
  274. priced from the usage Droid writes beside each log. See [its notes](docs/DROID.md).
  275. ### Everyday commands
  276. Work as usual; the plugin needs nothing from you. To see or change what it does, use its
  277. commands. They have the same names on every agent; only the way you type them differs:
  278. | Agent | Type a command as |
  279. |---|---|
  280. | Claude Code, Copilot CLI | `/tokeneconomizer:<command>` |
  281. | Codex | `$tokeneconomizer:<command>` |
  282. | Pi | `/te <command>` |
  283. | opencode | from a terminal: `~/.tokeneconomizer/bin/te --host opencode <command>` |
  284. | Cursor Agent | from a terminal: `~/.tokeneconomizer/bin/te --host cursor <command>` |
  285. | Grok Build | from a terminal: `~/.tokeneconomizer/bin/te --host grok <command>` |
  286. | Hermes Agent | from a terminal: `~/.tokeneconomizer/bin/te --host hermes <command>` |
  287. | Antigravity CLI | from a terminal: `~/.tokeneconomizer/bin/te --host antigravity <command>` (on Windows: `<plugin>\scripts\te.cmd --host antigravity <command>`, in the repository) |
  288. | Factory Droid | `/tokeneconomizer-<command>` (e.g. `/tokeneconomizer-status`) |
  289. | a terminal, in the repository | `~/.tokeneconomizer/bin/te <command>` |
  290. | Command | What it does |
  291. |---|---|
  292. | `status` | what it learned and did here, and what your sessions cost |
  293. | `microskills` | the facts it injects, and those still forming |
  294. | `toolprune` | the tools it left out, and the evidence (not on Pi, opencode, Hermes Agent, the Antigravity CLI or Factory Droid) |
  295. | `toolprune restore` | give them back; they will not be removed again |
  296. | `config` | every setting in effect |
  297. | `config set microskills=on` | turn a mechanism on (or `=off`) in this repository; add `--global` for every repository |
  298. Inside an agent, a command costs one model turn; from a terminal it is free. The other commands
  299. (`repos`, `doctor`, `config unset`, ...) and each agent's permission prompts are listed under
  300. [Commands](plugin/README.md#commands).
  301. ## Settings
  302. Tool pruning and the loop guard are on by default; with these defaults, the plugin calls a model
  303. only when a turn shows signs of looping: the judge, and the redirect it writes if it finds the
  304. turn stuck. Micro-skills is off by default, because its proposer adds model calls and how much it
  305. saves depends on the repository and the work you do there. What each of these calls reads, how
  306. often it runs and which model it uses are listed under
  307. [Model calls](plugin/README.md#model-calls-and-api-keys). On macOS 27, `local_model=fm` runs the
  308. judge on Apple's on-device model instead ([On-device side calls](plugin/README.md#on-device-side-calls-macos));
  309. it is off by default. Each mechanism has its own switch
  310. (`microskills`, `toolprune`, `loopguard`) that takes `on` or `off`, and the italic letters above
  311. are these settings:
  312. | | Setting | Default | What it sets |
  313. |---|---|---|---|
  314. | *k* | `microskills_propose_every` | 3 | sessions between runs of micro-skills' fact proposer |
  315. | *p* | `toolprune_evidence` | 10 | prompts a tool must go unused before it is left out |
  316. | *m* | `toolprune_min_sessions` | 2 | sessions those prompts must span |
  317. | *s* | `toolprune_sessions` | 5 | or this many sessions, of any length |
  318. | *q* | `toolprune_quiet_minutes` | 60 | minutes your sessions here must be idle before a deny list is written |
  319. | *e* | `loopguard.envelope_min_samples` | 5 | turns here that ended well (no failing check after the last edit) before the loop guard acts |
  320. | *c* | `loopguard.judge_confidence` | 0.7 | how sure the judge must be that a turn is stuck |
  321. | *r* | `loopguard_nudges` | 1 | redirects per turn before the guard only tells you |
  322. | *b* | `loopguard.backstop_mult` | 2.5 | how many times its usual length a churning turn may run before it is redirected without the judge |
  323. | | `droid_sidecall` | off | on Droid, allow the plugin's own model calls, which run `droid exec` |
  324. Change them with `config set`, shown here in Claude Code's form (other agents type it as in
  325. [Everyday commands](#everyday-commands)):
  326. ```text
  327. /tokeneconomizer:config set microskills=on # turn micro-skills on
  328. /tokeneconomizer:config set microskills_propose_every=5 # k = 5: propose facts less often
  329. /tokeneconomizer:config set toolprune_evidence=20 # p = 20: wait for twenty unused prompts
  330. /tokeneconomizer:config set loopguard_nudges=2 # r = 2: redirect twice before telling you
  331. ```
  332. On Droid, the plugin's own calls run `droid exec`, which writes a session log of its own, so
  333. they stay off until `config set droid_sidecall=on` (`TE_DROID_SIDECALL=1` does the same from a
  334. terminal). When on, they run with `--only-tools Read`, so `Read` is the only tool they may use.
  335. With them off, `microskills=envfacts` still learns and the loop guard keeps its rule-based
  336. backstop; only the paid fact proposer and the judge wait.
  337. Tool pruning counts prompts so that long sessions weigh more, and requires *m* sessions so that a
  338. single session never decides alone. It writes the deny list only once your sessions in the
  339. repository have been idle for *q* minutes (or, at the latest, a day after the list formed): a
  340. conversation resumed after its tools change must write its whole history to the prompt cache again
  341. instead of reading it, and after an idle hour that cache has expired anyway.
  342. On Claude Code, the plugin can also learn from a repository's earlier sessions, read from Claude
  343. Code's own logs oldest first and without any model call. This is off by default, and a
  344. repository's history is read only before the plugin has learned from any session there, so turn
  345. it on right after installing: with `config set history_import=on --global`, the first session in
  346. each repository reads that repository's earlier sessions in the background (see [Earlier
  347. sessions](plugin/README.md#earlier-sessions)). A deny list that rests on those earlier sessions
  348. waits for `toolprune apply`, even under `auto`.
  349. Besides `on` and `off`, two modes are useful: `toolprune=propose` only proposes the deny list, and
  350. nothing changes until you run `toolprune apply`; `microskills=envfacts` learns facts only from
  351. repeated failures, with no model calls.
  352. To change a single session, set an environment variable when you start the agent:
  353. `TE_DISABLE=1 claude` turns the whole plugin off, and `TE_LOOPGUARD=off codex` turns off one
  354. mechanism (likewise `TE_MICROSKILLS` and `TE_TOOLPRUNE`). Every setting and its default are
  355. listed under [Settings](plugin/README.md#settings); each one's environment variable is `TE_` plus
  356. its name in capitals.
  357. ## What it does on each agent
  358. Micro-skills and the loop guard work the same way on every agent. Each agent learns on its own:
  359. facts, tool evidence and the loop guard's sense of a usual turn are kept per agent and
  360. repository, while settings are shared. Tool pruning acts through each agent's own settings, so
  361. what it can leave out differs:
  362. | Agent | Tool pruning leaves out | Written to |
  363. |---|---|---|
  364. | Claude Code | single tools | `.claude/settings.local.json` |
  365. | Codex | capability packages | `.codex/config.toml` |
  366. | Copilot CLI | whole MCP servers | `.github/copilot/settings.local.json` |
  367. | Pi | nothing (Pi loads only four tools) | — |
  368. | Cursor Agent | nothing yet | — |
  369. | Grok Build | nothing yet | — |
  370. | opencode | nothing yet | — |
  371. | Hermes Agent | nothing yet | — |
  372. | Antigravity CLI | nothing yet | — |
  373. | Factory Droid | nothing (no persistent per-tool setting in the TUI) | — |
  374. Tool pruning adds only its own entries and never touches deny rules you wrote; a settings file it
  375. creates is kept out of git (`.git/info/exclude`). On Claude Code, the session-start line that says
  376. what it left out shows only in the detailed transcript (**Ctrl+O**), so check with
  377. `/tokeneconomizer:toolprune`. `toolprune restore` removes the plugin's entries and nothing else,
  378. and tools you give back are not removed again. If the plugin cannot edit a file safely (a
  379. `.codex/config.toml` your repository commits, a settings file that is not valid JSON, a symlink
  380. that leads out of the repository), the list stays a proposal and the session start says why;
  381. `toolprune apply` tries again. **[`docs/PLUGIN.md`](docs/PLUGIN.md)** records how each agent's
  382. hooks and settings were verified to behave, and **[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)**
  383. how the package fits together.
  384. ### When a turn gets stuck
  385. The loop guard first learns how long a turn in this repository usually runs: it waits until *e*
  386. turns here have ended well, on their own and with no failing check after the last edit. After
  387. that, a turn that shows signs of looping (the same failures repeating, or errors piling up) goes
  388. to the judge. One case is redirected without the judge: a turn that runs past *b* times the usual
  389. length while churning the same edits through the same failures. If a turn is still stuck after its
  390. redirects, you see one line that ends with how to stop it:
  391. > TokenEconomizer: this turn still looks stuck after a redirect (judge-stuck@0.82, 46 tool
  392. > calls). Press Esc to interrupt it.
  393. Where that line appears, and how to stop the turn, in the terminal UI and in a headless run
  394. (`claude -p`, `codex exec`, `copilot -p`, `pi -p`, `opencode run`, `hermes -z`):
  395. | Agent | Interactive: where it shows | How to stop | Headless: where it shows | How to stop |
  396. |---|---|---|---|---|
  397. | Claude Code | in Claude's reply | Esc | in the final reply | Ctrl+C |
  398. | Codex | in the conversation | Esc, then `/stop` | not shown | Ctrl+C |
  399. | Copilot CLI | in the conversation | Esc twice | on stdout | Ctrl+C |
  400. | Pi | as a notification | Esc | on stderr | Ctrl+C |
  401. | opencode | as a notification | Esc | on stderr | Ctrl+C |
  402. | Hermes Agent | in the model's reply | Ctrl+C | in the final reply | Ctrl+C |
  403. | Factory Droid | in the model's reply | Interrupt the agent | in the final reply | Ctrl+C |
  404. - **Claude Code** shows a plugin's own lines only in its detailed transcript (Ctrl+O), so the
  405. plugin asks Claude to repeat this one in its reply; the model may word it differently or leave
  406. it out.
  407. - **Codex**: Esc interrupts the turn, but a command it started keeps running until `/stop`.
  408. `codex exec` prints no hook messages.
  409. - **Pi**: Ctrl+C ends a headless run, but a command it started runs on until it finishes.
  410. - **opencode** 2.x prints the line to the opencode server's error output, not in its terminal UI.
  411. - **Hermes Agent**: the plugin asks the model to repeat the line, since no hook was found to reach
  412. the person's view; a model may word it differently or leave it out.
  413. In a headless run nobody may be watching, so a flagged turn runs until it ends or reaches the
  414. agent's own limits; afterwards, `te status` counts the redirects and "still stuck" notices.
  415. ## Repository
  416. | | |
  417. |---|---|
  418. | [`tokeneconomizer/microskills`](tokeneconomizer/microskills/) | Micro-skill synthesis and injection: facts learned from finished sessions |
  419. | [`tokeneconomizer/toolprune`](tokeneconomizer/toolprune/) | Tool pruning: unused tools and Codex capability packages |
  420. | [`tokeneconomizer/loopguard`](tokeneconomizer/loopguard/) | Failure-loop intervention: the per-call guard and its per-repository envelope |
  421. | [`tokeneconomizer/trace`](tokeneconomizer/trace/) | Each agent's session log, read into one shape |
  422. | [`tokeneconomizer/plugin`](tokeneconomizer/plugin/) | The runtime the hooks and the `te` command run |
  423. | [`plugin`](plugin/) | The installable plugin: manifests, hook files, launchers, slash commands, the Pi extension, the opencode and Hermes plugins, the Droid bundle (`.factory-plugin/`) |
  424. | [`experiments`](experiments/) | The harness, launchers and task sets behind the paper's results |
  425. | [`docs`](docs/) | `PLUGIN.md` (design, verified agent behavior), `ARCHITECTURE.md` (how the package fits together) and `DROID.md` (the Factory Droid adapter) |
  426. | [`tests`](tests/) | Offline tests for the package and the plugin |
  427. The package is standard-library only. Run the tests with `python -m pytest tests` (add
  428. `experiments/tests` for the benchmark side), and build a self-contained plugin bundle with
  429. `python3 scripts/build_plugin.py --out dist/marketplace`.
  430. ## Reproducing the experiments
  431. The code behind the paper's results -- a harness that runs Claude Code, Codex and the Copilot CLI
  432. on SWE-Bench and Web-Bench, the launchers, and the evaluated task sets -- is in
  433. **[`experiments/`](experiments/README.md)**, whose README gives the setup and one command per
  434. result. It is not part of the installed plugin; the two share only `tokeneconomizer/`.
  435. ## Citation
  436. ```bibtex
  437. @misc{li2026tokeneconomizer,
  438. title = {{TokenEconomizer}: Experience-Driven Black-Box Cost Control for Coding Agents},
  439. author = {Li, Aaron J. and Xu, Weijia and Singh, Chandan and Chen, Zixiao and
  440. Inala, Jeevana Priya and Siska, Charlotte and Tamersoy, Acar and Yu, Bin and
  441. Stoica, Ion and Galley, Michel and Gao, Jianfeng},
  442. year = {2026},
  443. eprint = {2610.22732},
  444. archivePrefix = {arXiv},
  445. primaryClass = {cs.CL},
  446. url = {https://arxiv.org/abs/2610.22732}
  447. }
  448. ```
  449. ## License
  450. [`MIT LICENSE`](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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