✂️ Tersio — Token Saver & Usage Tracker

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

🎯 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, Pi-in-go, OpenCode, and DeepSeek Harness, and cuts those costs:

⚡ 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, Pi-in-go, or DeepSeek Harness
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
tersio install --host dsh   # DeepSeek Harness — mounts the bundle into every dsh profile

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
dsh plugin --profile web add npm:@krtclcdy/tersio

The DeepSeek Harness desktop app installs through its Plugins pane instead: Add plugin → paste @krtclcdy/tersio, or a local checkout path while the bundle field is unreleased → restart the app. dsh plugin refuses the desktop profile by design, and tersio install --host dsh never writes it.

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

📊 Dashboard

tersio dashboard opens a local page for usage, cost, tools, traces, and savings. Other pages cover Models, Providers, Costs, Carbon, Requests, Errors, Tools, and Projects.

Quick start (Recommended) is the place to see the whole setup workflow: the modes, the agents, and how one turn moves from prompt to output.

Overview shows spend, requests, tokens, cache rate, and the latest calls.

🧪 Benchmarks

One model, GLM-5.3-Flash, five runs per prompt. Method: docs/BENCHMARK.md.

Base: 119 reply tokens, 1,616 total, 11 of 15. Agentic base: 40,176 tokens at 135.5s (pstack, RTK) and 70,784 at 150.3s (combo stacks). Agentic rows rest on 1 to 5 runs, so read them as smoke tests; no bill savings are claimed. Per-mode files: Caveman, Ponytail, pstack, RTK, Headroom, Combo, Combo + Headroom, Combo + pstack, Combo + all.

🔌 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. tersio install writes this same Tersio server entry into OMP, Pi, PiG, Deepseek Harness, and OpenCode, so there is no second MCP process. tersio_headroom carries savings, status, and retrieve for compressed content.

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 (savings by default; action: status for live proxy counters and routing; action: retrieve with a marker hash; 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:

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 snapshots, the backup schedule, retention (7 days to Forever; older usage rows drop on the next sync; transcripts stay), and Reset behind Advanced. Restore saves the current state first, then copies the snapshot over the live files; delete never touches live data. Both ask first, name what they change, and leave files outside the snapshot untouched. Reset confirms, clears the ledger and its RTK rows, hides the summary, and keeps transcripts, rtk history, and prices.

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.