✂️ Tersio — Token Saver & Usage Tracker

Token saver & usage tracker for coding agents: terse caveman replies, compact RTK shell output, lean Ponytail code, pstack rigor, and a gain dashboard — one-command combos over one shared extension tree.

Measured savings per mode, the prompt overhead each one adds, and the rerun protocol: docs/BENCHMARK_GUIDE.md.

🎯 What this is, and why you would use it

Coding agents bill you per token. Three of the costs you never asked for:

• Replies carry filler. The same three sentences, plus a greeting, a hedge, a recap, and a "hope this helps".
• Shell output is noise. A failing test prints hundreds of lines to reach the four that matter.
• The rules repeat every turn. Your agent re-reads its instructions on every single turn.

Tersio installs into Oh My Pi, pi, or OpenCode, and cuts those costs:

Mode	What it does for you
🪨 Caveman	Shorter replies. Answer first, filler gone, and code, commands, paths, and errors stay exact.
⚡ RTK	Condensed shell output, every signal kept. A failing test still names the test, the assertion, and the line.
🦥 Ponytail	Leaner code. YAGNI: no feature, option, or abstraction nobody asked for, and the shortest diff that still works.
🥔 pstack	Rigor mode. It applies a design principle when the moment fits, and owns the approach, the check, and the design.
🧩 Combo	One command sets all of the above, at three strengths.
📊 Dashboard	What you spent, per model and per day.

Every mode is a text block you can read in the repo. Measured savings and prompt overhead are published per mode in docs/BENCHMARK_GUIDE.md. No total-bill claim: the tests measure reply tokens, prompt overhead, and command output only.

Use an agent daily and pay per token? This is for you. Use one a few times a week? It is not worth installing.

⚡ Getting Started

All install paths in one table, with update and remove commands: INSTALL.md.

Default (macOS/Linux/WSL) — one line. Installs the CLI via npm, then runs the main installer (scope + Combo preset menus) in the same pass:

curl -fsSL https://github.com/KurutoDenzeru/tersio/releases/latest/download/install.sh | sh

Then run the CLI. Bare tersio opens a menu and asks which agent to install into:

tersio                      # menu — picks Oh My Pi, pi, or OpenCode
tersio install --host pi    # pi, non-interactive
tersio install --host omp   # Oh My Pi, non-interactive
tersio install --host opencode  # OpenCode, non-interactive

Or let each host install the package itself:

omp plugin install @krtclcdy/tersio
pi install npm:@krtclcdy/tersio
opencode plugin add @krtclcdy/tersio

Pick one install method per host, not both. Using both registers every command twice.

All hosts load the same six extensions from the same sources and read their session-start defaults from ~/.tersio/settings.json. All six load always.

One-off use without installing:

npm exec --yes --prefer-online --package=@krtclcdy/tersio@latest -- tersio install

Requirements

• OMP, pi, or OpenCode — all three are supported; pick one with tersio install --host <omp|pi|opencode>
• Node.js 20.12+ with npm. That is the requirement. The extensions load inside your host, the CLI runs under Node, and the package declares no Bun entry point
• Bun is optional. The installer prefers it when it is on PATH and falls back to npm. npm i -g alone installs everything. Bun also supplies SQLite in process, which is its only effect on the code
• SQLite comes from the runtime where it can: Bun, or Node 22.5+ through node:sqlite. An older Node needs the sqlite3 binary on PATH, and every engine answers identically
• macOS or Linux, native or WSL

On Windows, use WSL. There is no native Windows path: the installer, the extensions, and the RTK wiring are tested on macOS and Linux only. WSL has its own home directory, so install from inside WSL — command -v npm must resolve to a Linux path, not /mnt/c/.

🖥️ CLI

Command	Purpose
tersio install	Install (user scope: all OMP sessions)
tersio update	Refresh the CLI, extensions, and add-ons (RTK binary, Caveman rule, Ponytail)
tersio doctor	Check OMP, extension, Ponytail, RTK, and OpenCode service health (--fix repairs, --fix=<scope> one scope, --dry-run previews)
tersio usage	Ledger-backed usage + savings report
tersio dashboard	Open the Dashboard (--open, --export <file>, --port <n>, --currency <code>; serves localhost only)
tersio reset	Clear tersio statistics: usage ledger + a watermark that hides pre-reset rows from every derived view (Y/N confirm, --dry-run, --yes) — session transcripts and RTK history stay intact on disk
tersio reinstall	Refresh one agent's install: pick it, reinstall, then verify (--host picks without asking)
tersio uninstall	Remove extensions, registrations, the Ponytail plugin, and the rtk.ts OMP wiring (--keep-ponytail keeps Ponytail; --remove-rtk also removes the RTK binary)
tersio version	Print version

Flags: --dry-run, --yes/-y, --verbose, --combo-default/--caveman-default/--rtk-default/--ponytail-default/--pstack-default, --currency <code> (usage/dashboard display currency; flag wins, then the tersio settings default, then USD). Legacy --doctor / --uninstall forms still work.

⌨️ Commands reference

Mode switches live on their own commands; bare /tersio prints status. Every mode command, and every session start, prints the status line:

🧩 combo MAX: 🪨caveman=ULTRA ⚡rtk=ON 🦥ponytail=ULTRA 🥔pstack=ON

It is display-only — it never enters the model context, so it costs the session nothing.

Command	Purpose
/combo off|medium|balanced|max|status	One preset for all four modes (start here): medium = caveman lite · rtk on · ponytail lite · pstack on, balanced = full/full/on/on, max = ultra/ultra/on/on, and off disables every mode; per-mode tweaks drop to custom.
/caveman lite|full|ultra|megacave-lite|megacave-full|megacave-ultra|off|status	Terse replies with upstream-aligned Caveman levels. full, ultra, and megacave-full load upstream's own bodies byte for byte; lite, megacave-lite, and megacave-ultra are Tersio's own bodies for registers upstream defines but no longer ships, and each one names its upstream row in the file. The legacy wenyan spellings still resolve: wenyan → megacave-full, wenyan-lite → megacave-lite, wenyan-full → megacave-full, wenyan-ultra → megacave-ultra.
/rtk on|off|status	Controls RTK session guidance, rtk_run, and the automatic hook through shared RTK_DISABLED state. Exact bytes bypass RTK.
/ponytail off|lite|full|ultra|status	Minimal code using upstream Ponytail modes. Review runs separately through /ponytail-review.
/pstack on|off|status	Rigor mode, forked from pstack (MIT). The medium, balanced, and max presets turn it on; normal mode clears it.
/tersio status	Active modes + combo level; state persists and propagates to subagents.
/tersio check	Add-on version check
/tersio update <ponytail|rtk|caveman|all> [--dry-run]	Update add-ons, preview with dry-run
/tersio dashboard	Open the Dashboard.
/tersio usage	Ledger report for this machine (rows in ~/.tersio/usage.db, local only)
/tersio help	This table
/ai-addons	Add-on updater alias, still works.

🗂️ Files and backups

Shared, and identical for every host:

What	Path
Session-start defaults	~/.tersio/settings.json — combo, caveman, rtk, ponytail, pstack, and the display currency
RTK binary	~/.bun/bin/rtk (rtk.exe on Windows). The runtime resolves PATH first, then this managed path.
Usage ledger and price cache	~/.tersio/ — local only, nothing leaves the machine
usage.db host scope	~/.tersio/usage.db mirrors every agent Tersio reads: omp and pi transcripts, the OpenCode JSON tree, and the OpenCode v2 sqlite rows. Each row records its host and its agent kind, so a report splits by agent and by main agent or subagent.
Model prices	~/.tersio/prices.json caches LiteLLM's feed; ~/.tersio/prices.local.json is yours, keyed by model id or a * gateway prefix, and it wins over the feed. tersio usage prints an Unpriced line naming the keys to add.
Price sources	The host's own reported cost first, then prices.local.json, then the LiteLLM cache, then a default table the report labels a guess. A recorded zero is a real zero. A model counts as host-priced only when every message carried a cost.
Data snapshots	~/.tersio/backups/ — one directory per snapshot with a manifest.json; six are kept

Per host, written by tersio install --host <omp|pi|opencode>:

Host	Extensions	Ponytail
Oh My Pi	~/.omp/plugins/node_modules/@krtclcdy/tersio/extensions/ — the plugin manifest (omp.extensions) owns every mode extension, so the agent tree keeps only rtk's extensions/rtk.ts wiring, which config.yml registers by path	nested plugin dependency under ~/.omp/plugins/node_modules/, one Plugins row
pi	~/.pi/agent/extensions/{caveman,pstack,rtk,combo,commands,updater}/ — pi auto-discovers <agent-dir>/extensions, so there is nothing to register	npm:@dietrichgebert/ponytail, installed as a pi package
OpenCode	~/.config/opencode/plugins/tersio/ — registered in opencode.json plugins, so there is nothing else to register	bundled with Tersio; no separate package

All three hosts carry the same shared/ modules and the same mode extensions from the same sources.

omp merges the plugin manifest with the extension dir it discovers by default, so Tersio installs its extensions in one place per host. An install removes the copies an older build left in ~/.omp/agent/extensions/, because a second copy of the same file would load twice and one of them cannot resolve its own rule bodies.

The installer writes <file>.bak before replacing an extension source. tersio doctor --fix extensions restores a damaged tree, and doctor --fix registrations drops retired or duplicate config.yml entries.

Settings -> Data covers the snapshots that can put this machine's data back. A restore never deletes and a delete never touches the live data; each asks first and names the files it moves. Files a snapshot does not hold are left alone.

An OMP install also registers the package in ~/.omp/plugins, so it shows under OMP Settings → Plugins. Active modes reassert after Ponytail's prompt block on every top-level turn, including after history compaction.

🛠️ Troubleshooting

Ponytail or Combo command missing on OMP: confirm ~/.omp/plugins/package.json lists @krtclcdy/tersio, then run tersio install, restart OMP, and check tersio doctor. A damaged tree is repaired by tersio doctor --fix extensions.

RTK missing or not executable: run tersio install, then tersio doctor. On Linux/macOS: chmod +x ~/.bun/bin/rtk.

RTK savings and adoption: the Gain numbers read rtk's own history.db, which the binary writes on every host, so pi and OpenCode runs are already in them. The adoption row counts executed Bash calls from all three stores: the omp and pi session transcripts, and OpenCode's v2 sqlite or pre-v2 JSON message tree. The eligible command list comes from rtk rewrite itself, cached per binary version. Native tool calls (read/edit/eval) stay out of RTK by design, and exact bytes bypass RTK.

Checksum warning or failure: the installer aborts on RTK checksum mismatch but warns and continues when checksum metadata is unavailable; /tersio update rtk aborts when metadata is missing.

🤝🏻 Contributing

Contributions are always welcome, whether you're fixing bugs, improving docs, or shipping new features that make the project better for everyone.

Check out CONTRIBUTING.md to learn how to get started and follow the recommended workflow.

⚖️ License

This project is released under the MIT License, giving you the freedom to use, modify, and distribute the code with minimal restrictions.

For the full legal text, see the LICENSE file.