Microsoft Research, Microsoft Security and UC Berkeley have open-sourced TokenEconomizer, a plugin that makes coding agents cheaper to run in the repositories you use most. On SWE-Bench, the authors measured an 18.4–30.9% lower mean cost across five agent-model combinations, with Pass@1 higher in four of the five (paper, arXiv 2610.22732; repo). It works with Claude Code, Codex, the GitHub Copilot CLI and Pi, and the repository had passed roughly 1,600 stars within about two weeks of the paper appearing.
The interesting part is the method. It does not touch the model, the weights or the agent. It watches sessions your agent has already run in a repo and uses that history to trim waste in the next ones.
TL;DR
| Question | Answer |
|---|---|
| What is it? | An external controller plugin that learns across sessions in one repository |
| Who made it? | Microsoft Research, Microsoft Security, UC Berkeley (Aaron J. Li, Ion Stoica, Jianfeng Gao and others) |
| Headline result | 18.4–30.9% lower mean cost on SWE-Bench, cheaper in all 30 repo-by-agent cells |
| Other benchmarks | Web-Bench 16–21% lower; two security-auditing benchmarks 6–20% lower |
| License | Apache 2.0 |
| Needs its own API key? | No, it runs through your agent's own login |
| On by default | Tool pruning and the loop guard; micro-skills is off |
| Where learned data lives | ~/.tokeneconomizer on your machine |
Why coding agents are expensive in a way you can fix
The README's framing is blunt: coding agents are built to finish tasks, not to keep them cheap. Every turn pays again for the agent's instructions, every loaded tool definition, and the conversation so far. Most tokens in a long session are cached re-reads, which is why cache pricing matters (our Claude Code token efficiency guide walks through the mechanics).
The paper's argument is that agent efficiency is usually measured on isolated tasks, while real developers return to the same repository again and again. In that setting the same costs recur: the same fact rediscovered, the same unused tool sent with every request, the same kind of failing loop. The abstract describes these as "recurring environment-dependent token costs that existing methods struggle to reduce."
The three mechanisms
Each mechanism has its own on/off switch, so you can adopt them one at a time.
1. Micro-skills: remember how the repository works
Agents keep relearning small facts: a build step that must run first, a command spelled python -m pytest because pytest is not on the path, an environment variable a command needs, where generated files live. Micro-skills learns those facts from two sources: failures that repeat across sessions, and a model that reviews recent sessions every k sessions (default k = 3) and proposes facts.
A fact is stated at the start of each session only once three sessions have confirmed it, and it is dropped when later sessions contradict it. This mechanism is off by default. A cheaper mode, microskills=envfacts, learns only from repeated failures and makes no model calls.
2. Tool pruning: stop loading tools you never use
Every loaded tool's definition goes out with every request. If a tool goes unused over 10 prompts spread across at least 2 sessions, or over 5 sessions of any length, it is left out of the next sessions through the agent's own settings. One command (toolprune restore) gives them back, and restored tools are not removed again.
What gets pruned depends on the agent:
| Agent | What pruning removes | Written to |
|---|---|---|
| Claude Code | Single tools | .claude/settings.local.json |
| Codex | Capability packages | .codex/config.toml |
| Copilot CLI | Whole MCP servers | .github/copilot/settings.local.json |
| Pi | Nothing (it loads only four tools) | none |
| opencode | Nothing yet | none |
It only writes the deny list after your sessions in that repo have been idle for 60 minutes, because a conversation resumed after its tools change has to rewrite its whole history into the prompt cache instead of reading it. That is a thoughtful detail, and it is the same cache logic our token efficiency guide explains.
3. Loop guard: step in when a turn is stuck
A green bead looping around a chipped stepping stone, illustrating an agent failure loop that the loop guard interrupts
When a turn keeps hitting the same failures, a judge model checks whether it is stuck. If it is at least 70% sure, the agent gets a short redirect note, at most once per turn by default. If the turn is still stuck, TokenEconomizer prints a line telling you how to stop it, for example "Press Esc to interrupt it." It never stops a turn itself.
The guard waits until five turns in the repository have ended well, so it knows what a normal turn looks like. One case skips the judge: a turn that runs past 2.5 times its usual length while churning the same edits through the same failures.
What the paper measured
A glass jar with few green dots left, showing coding agent token budget in the TokenEconomizer results
The authors ran five agent-model combinations on 277 SWE-Bench tasks from six repositories. Each task was its own session, each repository's tasks ran in order, and learning started from nothing. Costs include every model call TokenEconomizer itself made, and are computed with cache pricing as billed.
| Benchmark | Reported cost change |
|---|---|
| SWE-Bench (277 tasks, 6 repos, 5 combos) | 18.4–30.9% lower mean cost; 5–40% within each repo and combination |
| Web-Bench (sequential web development) | 16–21% lower |
| Two security-auditing benchmarks, new repo per task | 6–20% lower (abstract: 6.4–21.2% across domains) |
| Task success | Pass@1 up in 4 of 5 combinations, "comparable" overall |
Note that the savings are smaller when every task lands in a fresh repository. That is expected: the whole idea is experience that accumulates, so it pays off for the repo you live in, not for one-off scratch work. The numbers come from the authors' own harness, which is published in the repo's experiments/ folder so others can rerun them. We have not rerun them, and no independent replication existed at publication time.
How to install it
The README gives per-agent commands. For Claude Code:
git clone https://github.com/microsoft/TokenEconomizer.git
claude plugin marketplace add "$PWD/TokenEconomizer"
claude plugin install tokeneconomizer@tokeneconomizer
Then start claude, trust the folder, run /tokeneconomizer:status, and once per machine (and again after Claude Code updates) run /tokeneconomizer:toolprune refresh-catalog. Codex uses codex plugin marketplace add and codex plugin add, with a "Trust all" step for hooks, and Pi installs with pi install git:github.com/microsoft/TokenEconomizer. Python 3.10 or newer must be on the PATH, and the package is standard-library only.
Everyday commands are the same across agents: status shows what it learned and what your sessions cost, microskills lists injected facts, toolprune shows what was left out, and config set microskills=on switches a mechanism on. Settings can be changed per repository or with --global, and TE_DISABLE=1 claude turns the plugin off for a single session.
Caveats before you rely on it
- Version pinning. Supported ranges are narrow: 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. Newer versions are untested, and the docs say older ones are not supported.
- It edits settings files. Pruning writes into agent settings and keeps them out of git via
.git/info/exclude. If it cannot edit a file safely, such as a.codex/config.tomlyour repo commits, the list stays a proposal. - Claude Code hides plugin lines. Claude Code shows a plugin's own messages only in the detailed transcript (Ctrl+O), so the plugin asks Claude to repeat the loop-guard notice, and the model may word it differently or skip it.
- Headless runs. In
claude -porcodex exec, nobody may be watching, so a flagged turn runs until it ends or hits the agent's own limits. - Benchmarks are not your repo. SWE-Bench is Python-heavy open-source issue fixing. Your monorepo may behave differently.
How it compares with other ways to cut agent cost
TokenEconomizer sits alongside, not instead of, other levers. ColGREP attacks search tokens with a local retrieval model. The Claude Code status-line token-burn claim is a reminder to measure where tokens actually go before optimizing. Prompt caching patterns on Bedrock show how much cached reads dominate bills, and gzip-compressed first-token latency work covers a different layer. If you extend Claude Code yourself, our mods guide shows how hooks and plugins fit together.
The distinctive part is that TokenEconomizer is a black box: it uses only the hooks and settings each agent already exposes, so it travels across vendors. That is also its limit, since it cannot fix what a vendor's harness does internally.
Why it matters now
Cost has become a first-class constraint. Companies are moving to consumption-based AI budgets, as in Accenture's per-person Claude funding cap, and subscription limits are being reshaped, as in our report on Anthropic's Max and Ultra plan change. A 20–30% cut at the harness level, if it holds in your repo, is the same order of magnitude as a plan upgrade, with no change in model or workflow.
A reasonable way to test it: install with defaults for two weeks, run /tokeneconomizer:status weekly, compare cost per merged change against your prior baseline, and turn on micro-skills only after you see what pruning and the loop guard do.
Related reading
- Claude Code token efficiency and prompt-cache guide
- ColGREP: local code search that cuts Claude Code tokens
- Claude Code status line and token burn: claimed vs verified
- Bedrock prompt caching and agent patterns
- Claude Code mods and TypeScript plugins
- Anthropic's Ultra plan and Max rename
Details reflect the TokenEconomizer README and arXiv paper as of October 30, 2026; supported agent versions and defaults may change.