✂️ Tersio — Token Saver & Usage Tracker

Token saver & usage tracker for coding agents: terse caveman replies, compact RTK shell output, lean Ponytail code, pstack rigor, Headroom compression, 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:

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) — 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

Windows — one line, the same pass through PowerShell:

irm https://github.com/KurutoDenzeru/tersio/releases/latest/download/install.ps1 | iex

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

tersio                      # menu — picks Oh My Pi, pi, OpenCode, or Pi-in-go
tersio install --host pi    # pi, non-interactive
tersio install --host omp   # Oh My Pi, non-interactive
tersio install --host opencode  # OpenCode, non-interactive
tersio install --host pig   # Pi-in-go (PiG), 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
pig install npm:@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

🔌 MCP

tersio mcp speaks the Model Context Protocol, so any MCP-capable client can read Tersio's data and set its modes mid-session. Nothing to run: the client starts Tersio when it needs it and stops it when done.

Add this entry under mcpServers in the client's MCP settings:

{
  "mcpServers": {
    "tersio": {
      "command": "tersio",
      "args": ["mcp"]
    }
  }
}

That is the whole setup. No extra command, no port, no token, and no process to keep alive.

Three tools become available: tersio_stats (requests, errors, tokens, cache rate, and cost for a range, in your display currency), tersio_activity (what Tersio changed, newest first), tersio_modes (read the session-start defaults, or set them: a Combo preset, or any single mode — caveman, rtk, ponytail, pstack, headroom — overriding its piece of the preset), and tersio_headroom (the savings Headroom's own ledger records, or action: memory, evals, and dashboard for the upstream commands Tersio does not reimplement).

🖥️ CLI

Flags: --dry-run, --yes/-y, --verbose, --combo-default/--caveman-default/--rtk-default/--ponytail-default/--pstack-default/--headroom-default, --currency <code> (usage/dashboard display currency; flag wins, then the dashboard's own 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 | 🍃 headroom=ON | 🧠 ponytail=ULTRA | 🥔 pstack=ON

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

🗂️ Files and backups

Shared, and identical for every host:

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

Tersio is agent-neutral: every host loads the same extensions and the same shared/ modules from the same sources. Only the paths and the registration differ, and the installer owns those. No host is the target.

Per host, in more words:

• Oh My Pi. The plugin manifest and the directory OMP discovers by default merge, so Tersio keeps one copy of each file and clears what an older build left in ~/.omp/agent/extensions/. A second copy would load twice, and one of the two cannot find its own rule bodies. The install also registers the package in ~/.omp/plugins, so it shows under Settings → Plugins.
• pi, PiG, and OpenCode. Their own install command registers what they need, so the table above is the whole story.

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

Settings -> Data holds the snapshots and the reset. A restore snapshots the current state first, then copies the chosen one over the live files; it never deletes, and a delete never touches the live data. Both ask first and name what they move, and a file a snapshot does not hold is left alone. The same pane clears the statistics behind a confirmation that names the ledger and RTK rows it would take, then empties the ledger and hides what it summarised. Session transcripts, rtk history, and prices stay on disk.

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. On Windows the binary is rtk.exe, and rtk publishes no aarch64-pc-windows build, so a Windows-on-ARM host has no rtk to install. The doctor's Platform row names this directly.

RTK savings and adoption: the Gain numbers read rtk's own history.db (%LOCALAPPDATA%\rtk on Windows), so pi and OpenCode runs are already in them. The adoption row counts executed Bash calls from the omp and pi transcripts and OpenCode's v2 sqlite or pre-v2 JSON tree. The eligible list comes from rtk rewrite, cached per binary version. Native tool calls (read/edit/eval) 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.