What is TokenEconomizer?
TokenEconomizer is a plugin that makes coding agents cheaper in repositories you return to, without changing the agent or the model. After each finished session it updates three things: micro-skills (repository facts that sessions keep rediscovering, such as running python -m pytest because pytest is missing), a list of tools the repository never uses, which it removes through the agent's own settings, and a loop guard that asks a judge model whether a repeatedly failing turn is stuck and, if so, sends one redirect.
It supports Claude Code, Codex, GitHub Copilot CLI and Pi, with experimental support for Cursor, opencode and Hermes. Tool pruning and the loop guard are on by default; micro-skills are off. The plugin needs no API key of its own: its model calls run through your agent's CLI on your existing plan, and what it learns is kept in ~/.tokeneconomizer.
It comes with the paper TokenEconomizer: Experience-Driven Black-Box Cost Control for Coding Agents (arXiv 2610.22732) by researchers at Microsoft Research, Microsoft Security and UC Berkeley. It is written in Python using only the standard library, needs Python 3.10 or later and is licensed Apache-2.0. Version 0.1.0 came out on 26 October 2026.
Is TokenEconomizer worth it?
TokenEconomizer is a cost add-on for coding agents with a controlled study behind it, and the study supports a modest, believable claim: in a repository you keep coming back to, the agent can stop paying for the same mistakes and for tools it never calls. The paper ran 277 SWE-Bench tasks from 6 repositories in order, three seeds each, across five agent and model settings. It reports mean cache-aware cost 18.4 to 30.9% lower than the unmodified agent, lower in all 30 repository and setting cells (by 5.2 to 40.1%), with the plugin's own model calls charged to the task that triggered them. Under the same setup, RTK alone raised cost in 12 of those cells and Aider's RepoMap in 15.
The caveats are in the paper itself. Pass@1 rose in 4 of 5 settings and fell 1.0 point on Claude Code with Opus 4.8; the paper reports standard deviations over three seeds but no significance tests, and most differences are one or two points. Its hyperparameters were set in development runs on the same six repositories, the task streams are independent fixes rather than real user sessions, and the authors say interactive use is untested. Savings also take time: every repository except xarray cost more at first, and all were cheaper by the sixth task.
The shipped defaults are not the configuration behind the headline. The 18.4 to 30.9% figures use all three mechanisms, but the plugin turns micro-skills off by default. On Claude Code, the paper's ablation puts tool pruning alone at 13.2% (Sonnet 5) and 17.7% (Opus 4.8), micro-skills alone at 11.8 and 14.3%, and the loop guard alone at 7.1 and 5.4%. The one independent test we found, by yoDEV on DEV Community before the v0.1.0 tag, fits that picture: across 8 bug fixes in a small Python repository, run twice per side, pruning removed 284 tools and cut context per request by 31%, session cost fell 15% ($0.72 to $0.61) over only 4 sessions, micro-skills never activated and the loop guard never fired.
The data story is cleaner than most. There is no extra API key; judge, redirect and fact-proposer calls go through your own agent's CLI (claude -p, codex exec, copilot -p), defaulting to Haiku on Claude Code, and the docs say no call receives file contents or your prompts. The judge sees the last 24 actions with commands cut to 90 characters, at most about 1,500 tokens. Learned state stays in ~/.tokeneconomizer and the docs mention no telemetry. Pruning does write deny lists into project files such as .claude/settings.local.json, hidden from git through .git/info/exclude.
It is an early research release. The repository was created on 13 October 2026, has about 4,800 stars and 16 open issues and pull requests, including a Windows memory leak in the hook launcher (#144) and a loop-guard race when tools run in parallel (#142). It is tested against narrow agent version ranges, such as Claude Code 2.1.300 to 2.1.310, and newer versions are untested. Where RTK compresses command output, TokenEconomizer changes what the agent loads and repeats, so the two stack: the paper's best Opus 4.8 result, 33.2% lower cost, combined them.
Where it earns its place
A backend developer on an API plan who runs Claude Code in one Django monorepo every day
Stop paying for MCP tools and connectors the repository never uses
Install the plugin and leave the defaults; after several sessions tool pruning writes a deny list to .claude/settings.local.json, after about an hour idle so it does not break a warm prompt cache. In yoDEV's small test this removed 284 tools and cut context per request by 31%; toolprune restore brings them back.
An engineering manager watching agent spend for a ten-person team on Codex
See whether agent costs in the team's main repositories actually fall
Each developer installs it; status and the per-repository ledger.jsonl report session costs including the plugin's own calls. Expect the first sessions to cost more and judge the result after a week of normal work, not on the paper's 18.4 to 30.9%.
A developer whose agent keeps rerunning the same failing test command
Break long failure loops without stopping the agent by hand
After 5 successful turns in the repository, the loop guard sends a stuck-looking turn to a judge on your plan (Haiku by default on Claude Code) and redirects once if the judge is at least 0.7 confident. It never stops a turn itself; in headless runs a flagged turn continues to the agent's own limits.
Before you commit
- Setup
- Needs Python 3.10 or later. Clone the repository and keep the clone in place, then add it as a plugin marketplace and install tokeneconomizer@tokeneconomizer (claude, codex or copilot plugin commands); Pi installs straight from git. On Claude Code and Copilot CLI, run toolprune refresh-catalog once per machine and after agent updates.
- Integrations
- Claude Code 2.1.300 to 2.1.310, Codex 0.153.1 to 0.164.0, Copilot CLI 1.0.83 to 1.0.102 and Pi 1.2.0 to 1.3.0 are tested; Cursor, opencode and Hermes are experimental. Pruning removes single tools on Claude Code, capability packages on Codex and whole MCP servers on Copilot CLI, and nothing on the others.
- Data and privacy
- Facts, tool evidence, loop history, a cost ledger and an error log stay in ~/.tokeneconomizer; deleting that folder removes what it learned. Model calls go through your agent's CLI and, per the docs, never include file contents or your prompts. No telemetry is documented. Apache-2.0.
- Cost at scale
- The plugin is free; its judge and fact-proposer calls bill to your plan, and with the defaults it calls a model only when a turn looks stuck. No hosted or paid edition is published.
- Limits
- Savings need repeat sessions in one repository and start negative. With Copilot BYOK the plugin's model calls are paused. Running a plugin command inside the agent costs a model turn. 16 open issues and pull requests, including a Windows memory leak and a parallel-tool race in the loop guard.
What’s good
- Savings measured in a paper with three seeds and its own calls counted
- No extra API key; model calls run through your agent's CLI
- Learned state stays local in ~/.tokeneconomizer
- Every action is reversible, and a failing plugin leaves the session running
What’s not
- Micro-skills, part of the headline result, are off by default
- Costs more for the first few tasks in a new repository
- Hyperparameters tuned on the same repositories it was tested on
- v0.1.0 with open Windows and concurrency bugs and narrow tested agent versions
Best for
Developers and teams paying per token for Claude Code, Codex or Copilot CLI who run the agent in the same few repositories day after day.
TokenEconomizer alternatives
TokenEconomizer: common questions
- Is TokenEconomizer worth it?
- A cost cutter with a real study behind it, worth adding to repositories you work in every day, provided you expect less than the paper's headline from the shipped defaults. We rate it 3.8 out of 5.
- How much does TokenEconomizer cost?
- Free under the Apache-2.0 licence; its own model calls are billed to your existing agent plan or key.
- What are the downsides of TokenEconomizer?
- Micro-skills, part of the headline result, are off by default; costs more for the first few tasks in a new repository; hyperparameters tuned on the same repositories it was tested on; v0.1.0 with open Windows and concurrency bugs and narrow tested agent versions.
- Who is TokenEconomizer best for?
- Developers and teams paying per token for Claude Code, Codex or Copilot CLI who run the agent in the same few repositories day after day.
- How much does TokenEconomizer cost for a team or in production?
- The plugin is free; its judge and fact-proposer calls bill to your plan, and with the defaults it calls a model only when a turn looks stuck. No hosted or paid edition is published.
- Is TokenEconomizer safe for company data?
- Facts, tool evidence, loop history, a cost ledger and an error log stay in ~/.tokeneconomizer; deleting that folder removes what it learned. Model calls go through your agent's CLI and, per the docs, never include file contents or your prompts. No telemetry is documented. Apache-2.0.
- What are the best TokenEconomizer alternatives?
- The closest alternatives we have reviewed are rtk (Rust Token Killer), context-mode and ccusage.
Answers checked Nov 5, 2026.