# TokenEconomizer

A plugin for Claude Code, Codex, the Copilot CLI and Pi that reads finished sessions and changes
what later sessions in the same repository pay for: micro-skills, tool pruning, and a loop guard.
See `README.md` for the overview and the method, `docs/PLUGIN.md` for the design and the verified
agent behavior, and `docs/ARCHITECTURE.md` for how the package fits together.

## Layout
- `tokeneconomizer/` — the one Python package, standard library only
  - `microskills/` — learn repository facts from finished sessions; render the injected block
  - `toolprune/` — unused-tool evidence and the deny-list proposal; Codex capability packages
  - `loopguard/` — the per-call failure-loop guard and its per-repository envelope
  - `trace/` — each agent's session-log format (Claude Code, Codex, Copilot CLI, Pi, opencode)
  - `plugin/` — the runtime: hook dispatch, per-repository state, settings, the `te` CLI
  - `config.py`, `ledger.py`, `pricing.py`, `domain.py`, `stage.py` — shared by all three
- `plugin/` — the installable plugin directory: manifests per agent, hook files, launchers
  (`scripts/te`, `scripts/te-hook`), slash commands (`slash-commands/`, named in the Claude Code
  and Copilot manifests, since Codex would turn a `commands/` folder into duplicate skills), Codex
  skills (`codex-skills/`, Codex having no plugin slash commands), the Pi extension; `lib/` links
  the package
- `experiments/` — benchmark-only: `te_bench/` (adapters, arms, facade, benchmark-only
  controllers), `te_harness/` (Docker runners), `scripts/`, `workloads/`, its own `tests/`;
  its `README.md` is the run book
- `package.json` — the repository as a Pi package (`pi install git:github.com/…`); it names
  the same extension as `plugin/package.json`, which a test pins
- `scripts/build_plugin.py` — a self-contained plugin bundle for marketplace installs
- `tests/` — offline tests for the package and the plugin

## Conventions
- The mechanisms (`microskills`, `toolprune`, `loopguard`, `trace`) never import
  `tokeneconomizer.plugin`, and nothing under `tokeneconomizer/` imports `experiments/`; both
  are pinned by `tests/test_plugin_package.py`.
- Standard library only, Python >= 3.10. A hook must start fast and fail open: any exception in
  a hook becomes `{}` and a line in `~/.tokeneconomizer/errors.log`.
- On-disk state names (`injection.json`, `untool.json`, `envelope.json`, event kinds) are a
  compatibility surface; renaming them strands what users have learned.
- Settings keep their earlier names as aliases (`inject`, `untool`, `spiral`, ...; see
  `plugin/config.py`); write new code against the current names.
- No run outputs in the repository: transcripts, rows, streams, figures rendered from runs and
  tables derived from them stay out of git (`.gitignore`). The one exception is the paper's
  headline results in `README.md` (the line under the badges, the Results section, and the
  teaser's closing results, which read `docs/assets/results_overview.py`'s `ROWS`; that script
  also draws `results_overview.*`, which the README no longer shows): quoted from the paper's
  Table 1 and attributed to it. Change them only with the paper, and redraw both figures with
  `python docs/assets/results_overview.py` and `python docs/assets/teaser.py --plex FONTS`
  (its docstring says where to get IBM Plex). The teaser's middle act is a schematic with
  made-up sessions and no numbers.
- The plugin's own text (`plugin/`, its manifests, slash commands and skills, and what the
  hooks print) makes no claims of effect.
- Tests: `python -m pytest tests experiments/tests`. A change to what the plugin learns or
  decides should be checked against recorded sessions, not only the unit tests.
- Every model-backed test goes through the agent's own CLI on a provider you control
  (OpenRouter in development); never hard-code a key.