# TokenEconomizer

> A plugin that learns from past sessions to make coding agents cheaper in the repositories you use them in

- Category: App Orchestration / Context Compression & Token Budgets
- Language: Python
- Licence: Apache-2.0
- Repository: https://github.com/microsoft/TokenEconomizer
- Canonical page: https://ai-tldr.dev/tools/tokeneconomizer/
- Updated: 2026-10-26

## In short

TokenEconomizer is a plugin that makes coding agents cheaper to run in the repositories you work in often, without changing the agent itself. It sits in the Context Compression & Token Budgets category of the App Orchestration tools and is open-source, written in Python and licensed Apache-2.0. To get started: clone and install the plugin.

## Overview

TokenEconomizer is a plugin that makes coding agents cheaper to run in the repositories you work in often, without changing the agent itself. It comes from Microsoft Research, Microsoft Security and UC Berkeley, alongside the paper "TokenEconomizer: Experience-Driven Black-Box Cost Control for Coding Agents" (arXiv 2610.22732), and installs into Claude Code, Codex, the GitHub Copilot CLI and Pi, with experimental support for opencode.

The idea is that every turn of an agent pays again for its instructions, every loaded tool and the conversation so far — and developers run the same agent on the same repository over and over, so much of that cost repeats. TokenEconomizer reads the logs of the sessions an agent has already finished in a repository and uses that experience to cut waste in the sessions that follow, through three mechanisms: micro-skills (repository facts the agent keeps rediscovering, stated at session start), tool pruning (tools that go unused are left out of later sessions through the agent's own settings) and failure-loop intervention (a judge model checks whether a turn is stuck repeating the same failures and, if so, redirects it once).

Every action is designed to be reversible: facts that later sessions contradict are dropped, pruned tools come back with one command, and the loop guard only redirects and notifies — stopping a turn stays your call. The plugin's own model calls run through your agent on the same plan or login and are counted in its cost reports, and what it learns stays on your machine in `~/.tokeneconomizer`. In the paper's runs on 277 SWE-Bench tasks across five agent–model combinations, the authors report 18.4–30.9% lower mean cost, with Pass@1 up in four of the five combinations. The v0.1.0 release shipped in October 2026; the package is standard-library Python 3.10+ under the Apache-2.0 license.

## What it does

- Micro-skills: learns repository facts (the build step that must run first, `python -m pytest` where `pytest` is missing, a required environment variable) from repeated failures and a periodic model review, and states them at session start once three sessions confirm them
- Tool pruning: tools left unused over a set number of prompts and sessions are excluded from later sessions through the agent's own settings, with `toolprune restore` to bring them back
- Failure-loop intervention: a judge model checks turns that keep hitting the same failures and redirects a stuck turn, then tells you how to stop it — it never stops a turn itself
- Works with Claude Code, Codex, the GitHub Copilot CLI and Pi, plus experimental opencode support, with the same command names on every agent
- Cost counted as billed, using cache pricing and including the plugin's own model calls, in a per-repository `status` report
- Each mechanism switchable per repository or globally, with tunable thresholds and a propose-only mode for tool pruning

## Getting started

You need one of the supported agents, signed in any way it supports, and Python 3.10 or newer on PATH. The plugin needs no API key of its own. These steps follow the project README for Claude Code; Codex, the Copilot CLI, Pi and opencode have their own install lines there.

1. Clone and install the plugin

   Claude Code runs the plugin from the clone, so keep it in place. Keep the marketplace path absolute.

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

2. Check it is running

   Start `claude` in one of your repositories, trust the folder, and run the status command, allowing its script if asked. It prints a short status block.

```text
/tokeneconomizer:status
```

3. Record the tool catalog

   Once per machine, and again after Claude Code updates, record every tool a session loads so tool pruning can consider all of them. This makes no model call.

```text
/tokeneconomizer:toolprune refresh-catalog
```

4. Work as usual, then inspect what it did

   The plugin needs nothing from you while you work. Its commands show what it learned and what your sessions cost; from a terminal in the repository the same commands run for free via `~/.tokeneconomizer/bin/te`.

```text
/tokeneconomizer:status       # what it learned and did here, and what sessions cost
/tokeneconomizer:microskills  # the facts it injects, and those still forming
/tokeneconomizer:toolprune    # the tools it left out, and the evidence
/tokeneconomizer:toolprune restore
```

5. Tune or switch mechanisms

   Tool pruning and the loop guard are on by default; micro-skills is off by default because its fact proposer adds model calls. Change settings with `config set`, or disable the plugin for one session with an environment variable.

```text
/tokeneconomizer:config set microskills=on
/tokeneconomizer:config set toolprune_evidence=20

# one session without the plugin
TE_DISABLE=1 claude
```

## When to use it

- Lower the bill of a coding agent you run day after day on the same repositories
- Stop an agent from re-learning the same build and test quirks at the start of every session
- Trim tool definitions a repository never uses from every request the agent sends
- Catch agent turns stuck in a loop of the same failing edits before they burn more tokens

## Version history

- 2026-10-26 v0.1.0: First release: the micro-skills, tool-pruning and failure-loop-intervention plugin for Claude Code, Codex, the GitHub Copilot CLI and Pi, published with the TokenEconomizer paper.