Skip to content

Experience-Driven Black-Box Cost Control for Coding Agents

README: opencode, as experimental

Aaron4184ee6ab16f
diff --git a/README.md b/README.md
index 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 turn
itself.
-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 or
login 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/TokenEconomizer
Start `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 all
of 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 versions
have 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's
full 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 it
creates 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 the
plugin 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 the
agent'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.md
index 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) ·