microsoft/TokenEconomizer

microsoft/TokenEconomizer

Description: Experience-Driven Black-Box Cost Control for Coding Agents

Language: Python

License: Apache-2.0

Stars: 441

Forks: 42

Open issues: 1

Created: 2026-10-13T04:16:50Z

Pushed: 2026-10-29T04:53:59Z

Default branch: main

Fork: no

Archived: no

README:

TokenEconomizer: Experience-Driven Black-Box Cost Control for Coding Agents

Aaron J. Li1, Weijia Xu2, Chandan Singh2, Zixiao Chen3, Jeevana Priya Inala2, Charlotte Siska3,

Acar Tamersoy3, Bin Yu1, Ion Stoica1, Michel Galley2, Jianfeng Gao2

1UC Berkeley 2Microsoft Research 3Microsoft Security

Our measurement on SWE-Bench tasks: 18.4–30.9% lower mean cost across five agent–model combinations, cheaper in all 30 repository × combination cells, and Pass@1 up in 4 of 5. Results

TokenEconomizer makes coding agents cheaper to run in the repositories you work in often, without changing the agent itself. It learns from the sessions an agent has already run in a repository, and uses that experience to cut waste in the sessions that follow. It has three mechanisms:

• Micro-skills: remember how the repository works. Sessions keep rediscovering the same

facts: a build step that must run first, the spelling of a command that works here (python -m pytest where pytest is missing, npx tsc where tsc is), an environment variable a command needs, where generated files live. Micro-skills learns such facts, in any language, from two sources: failures that repeat across sessions, and a model that reviews the recent sessions every *k* sessions (*k* = 3) and proposes facts. A fact is stated at the start of each session once three sessions have confirmed it, and dropped when later sessions contradict it.

• Tool pruning: stop loading tools that go unused. Every loaded tool's definition is sent with

every request. A tool that goes unused over *p* prompts spread across at least *m* sessions, or over *s* sessions of any length (*p* = 10, *m* = 2, *s* = 5), is left out of the next sessions through the agent's own settings. One command brings it back.

• Failure-loop intervention (the loop guard): step in when a turn is stuck. When a turn (the

agent's work on one prompt) keeps hitting the same failures, a judge model checks whether it is stuck. If the judge is at least *c* sure (*c* = 0.7), the agent gets a redirect (a short note, added to its context, to try another approach), at most *r* times per turn (*r* = 1). If the turn is still stuck after that, TokenEconomizer tells you how to stop it; it never stops a turn itself.

TokenEconomizer is a plugin for Claude Code, Codex, the GitHub Copilot CLI and Pi, with experimental support for opencode. Each italic letter above is a setting, shown with its default ([Settings](#settings)), and each mechanism can be turned on or off. The plugin announces each action in one line, and if any part of it fails, your session carries on as if it were not installed. Its model calls (the fact proposer, and the judge with the redirect it writes) run through your own agent, on the same plan or login, and their cost is included in its reports. What it learns stays on your machine, in ~/.tokeneconomizer.

Results

The paper ran five agent–model combinations on the same 277 SWE-Bench tasks from six repositories. Each task ran as its own session, and each repository's tasks ran in order, starting with nothing learned. Costs include every model call TokenEconomizer made. Within each repository and combination, cost fell by 5–40%. The savings held on Web-Bench (16–21% lower) and on two security-auditing benchmarks where every task is in a new repository (6–20% lower). The project page has interactive charts, per-repository numbers and nine annotated runs, and [experiments/](experiments/README.md) reruns the SWE-Bench and Web-Bench experiments.

How it works

Coding agents are built to finish tasks, not to keep them cheap. Every turn pays again for the agent's instructions, every loaded tool, and the conversation so far. Developers use the same agent on the same repository again and again, so much of that cost repeats: the same facts rediscovered, the same unused tools sent, the same kinds of failing loops. TokenEconomizer leaves the agent's model, weights and code alone and learns across a repository's sessions instead of treating each one on its own, so whatever the plugin spends is paid back over the sessions that follow. Four principles guide the mechanisms:

• Work through what the agent already reads. Facts enter the context at session start, and

tools are removed through the agent's own settings, so nothing depends on the agent learning a new tool.

• Count cost as it is billed. Most tokens in a session are cached re-reads, so cost is

computed with cache pricing, and it includes the plugin's own model calls.

• Protect task success. Facts form only from repeated evidence, tools are removed only after

going unused, and the loop guard leaves alone a turn that is still making progress.

• Keep every action reversible. A fact that later sessions contradict is dropped, removed

tools can be given back, and the loop guard only redirects and tells you: stopping a turn is your call.

Quick start

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...