Experience-Driven Black-Box Cost Control for Coding Agents
Python agentic-aiagentic-codingai-codingai-coding-assistantanthropicartificial-intelligenceclaude-codecodexcoding-agentcoding-agentscost-optimizationcost-reductiondeveloper-toolsgithub-copilotllmopen-sourceopenaiproductivitytoken-optimization
README: opencode, as experimental
Aaron4184ee6ab16f
diff --git a/README.md b/README.mdindex e8116b6..44d9b77 100644--- a/README.md+++ b/README.md@@ -63,13 +63,13 @@ mechanisms:turn is still stuck after that, TokenEconomizer tells you how to stop it; it never stops a turnitself.-TokenEconomizer is a plugin for **Claude Code**, **Codex**, the **GitHub Copilot CLI** and **Pi**.-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`.+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@@ -107,15 +107,15 @@ follow. Four principles guide the mechanisms:## Quick start-You need one of the four agents, signed in any way it supports, and Python 3.10 or newer on+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 orlogin works.### Install-Run these commands in the folder where you want to keep the clone. Claude Code, Codex and the-Copilot CLI run the plugin from the clone, so leave it in place. Then start the agent in one of-your repositories.+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**@@ -161,6 +161,18 @@ pi install git:github.com/microsoft/TokenEconomizerStart `pi` and run `/te status`.+**opencode** (experimental)++```sh+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.+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 allof them. Keep the marketplace path absolute, as above: the Copilot CLI reads a relative path such@@ -170,7 +182,7 @@ To update:| Agent | Update ||---|---|-| Claude Code, Copilot CLI | `git pull` in the clone |+| Claude Code, Copilot CLI, opencode | `git pull` in the clone || Codex | `git pull` in the clone, then the `codex plugin add` line again || Pi | `pi update --extensions` |@@ -185,6 +197,7 @@ uninstalling, using Copilot with your own model key, and troubleshooting.| Codex | 0.153.1 to 0.164.0 | not supported || Copilot CLI | 1.0.83 to 1.0.102 | not supported || Pi | 1.2.0 to 1.3.0 | 0.99.x: load the extension by path (below) |+| opencode (experimental) | 1.19.5 and 2.2.0 | not tested |The commands above were tested on the oldest and newest version in each range; newer versionshave not been tested yet.@@ -193,6 +206,8 @@ have not been tested yet.- **Pi 0.99.x**: instead of `pi install`, clone the repository and start each session with`pi --extension /path/to/TokenEconomizer/plugin/pi/tokeneconomizer.ts`, using your clone'sfull path; `git pull` in the clone updates it.+- **opencode** support is experimental: it was tested on 1.19.5 and 2.2.0 only, and not in the+ 2.x terminal UI.### Everyday commands@@ -204,13 +219,14 @@ commands. They have the same names on every agent; only the way you type them di| Claude Code, Copilot CLI | `/tokeneconomizer:<command>` || Codex | `$tokeneconomizer:<command>` || Pi | `/te <command>` |+| opencode | from a terminal: `~/.tokeneconomizer/bin/te --host opencode <command>` || a terminal, in the repository | `~/.tokeneconomizer/bin/te <command>` || Command | What it does ||---|---|| `status` | what it learned and did here, and what your sessions cost || `microskills` | the facts it injects, and those still forming |-| `toolprune` | the tools it left out, and the evidence (not on Pi) |+| `toolprune` | the tools it left out, and the evidence (not on Pi or opencode) || `toolprune restore` | give them back; they will not be removed again || `config` | every setting in effect || `config set microskills=on` | turn a mechanism on (or `=off`) in this repository; add `--global` for every repository |@@ -279,6 +295,7 @@ what it can leave out differs:| Codex | capability packages | `.codex/config.toml` || Copilot CLI | whole MCP servers | `.github/copilot/settings.local.json` || Pi | nothing (Pi loads only four tools) | — |+| opencode | nothing yet | — |Tool pruning adds only its own entries and never touches deny rules you wrote; a settings file itcreates is kept out of git (`.git/info/exclude`). On Claude Code, the session-start line that says@@ -304,7 +321,7 @@ redirects, you see one line that ends with how to stop it:> calls). Press Esc to interrupt it.Where that line appears, and how to stop the turn, in the terminal UI and in a headless run-(`claude -p`, `codex exec`, `copilot -p`, `pi -p`):+(`claude -p`, `codex exec`, `copilot -p`, `pi -p`, `opencode run`):| Agent | Interactive: where it shows | How to stop | Headless: where it shows | How to stop ||---|---|---|---|---|@@ -312,6 +329,7 @@ Where that line appears, and how to stop the turn, in the terminal UI and in a h| Codex | in the conversation | Esc, then `/stop` | not shown | Ctrl+C || Copilot CLI | in the conversation | Esc twice | on stdout | Ctrl+C || Pi | as a notification | Esc | on stderr | Ctrl+C |+| opencode | as a notification | Esc | on stderr | Ctrl+C |- **Claude Code** shows a plugin's own lines only in its detailed transcript (Ctrl+O), so theplugin asks Claude to repeat this one in its reply; the model may word it differently or leave@@ -319,6 +337,7 @@ Where that line appears, and how to stop the turn, in the terminal UI and in a h- **Codex**: Esc interrupts the turn, but a command it started keeps running until `/stop`.`codex exec` prints no hook messages.- **Pi**: Ctrl+C ends a headless run, but a command it started runs on until it finishes.+- **opencode** 2.x prints the line to the opencode server's error output, not in its terminal UI.In a headless run nobody may be watching, so a flagged turn runs until it ends or reaches theagent's own limits; afterwards, `te status` counts the redirects and "still stuck" notices.@@ -332,7 +351,7 @@ agent's own limits; afterwards, `te status` counts the redirects and "still stuc| [`tokeneconomizer/loopguard`](tokeneconomizer/loopguard/) | Failure-loop intervention: the per-call guard and its per-repository envelope || [`tokeneconomizer/trace`](tokeneconomizer/trace/) | Each agent's session log, read into one shape || [`tokeneconomizer/plugin`](tokeneconomizer/plugin/) | The runtime the hooks and the `te` command run |-| [`plugin`](plugin/) | The installable plugin: manifests, hook files, launchers, slash commands, the Pi extension |+| [`plugin`](plugin/) | The installable plugin: manifests, hook files, launchers, slash commands, the Pi extension, the opencode plugin || [`experiments`](experiments/) | The harness, launchers and task sets behind the paper's results || [`docs`](docs/) | `PLUGIN.md` (design, verified agent behavior) and `ARCHITECTURE.md` (how the package fits together) || [`tests`](tests/) | Offline tests for the package and the plugin |diff --git a/plugin/README.md b/plugin/README.mdindex fbce512..5797ce7 100644--- a/plugin/README.md+++ b/plugin/README.md@@ -1,8 +1,8 @@# TokenEconomizer plugin-How to install and use TokenEconomizer in Claude Code, Codex, the GitHub Copilot CLI, Pi and (experimental) opencode. What-the plugin does and why is in the [main README](../README.md); its design and the verified-behaviour of each agent are in [`docs/PLUGIN.md`](../docs/PLUGIN.md).+How to install and use TokenEconomizer in Claude Code, Codex, the GitHub Copilot CLI, Pi and+(experimental) opencode. What the plugin does and why is in the [main README](../README.md); its+design and the verified behaviour of each agent are in [`docs/PLUGIN.md`](../docs/PLUGIN.md).- [Before you start](#before-you-start)- Install and use it on [Claude Code](#claude-code) · [Codex](#codex) ·