Hiutaky/token-saver

💸 Token Saver

See how much money your local (free) AI actually saves you.

Token Saver is a drop-in Hermes Agent plugin. If you run Hermes on a local model — Ollama, LM Studio, llama.cpp, or any OpenAI-compatible endpoint that costs you $0 — this plugin turns your real, per-request token usage into the dollar amount it would have cost on hosted pricing, and shows you the gap: that's what you just saved.

No keys. No telemetry. No build step. Pure stdlib, all local. (◕‿◕)

Why "saver"?

Running a model locally is free — but "free" is hard to feel. You type, the model answers, and nothing on your bill changes. You never see the value.

Token Saver makes the value visible. It prices every request you make with the real OpenRouter rates for that exact model (fetched live, cached for 72h), accumulates the hypothetical cost across your session, and shows it three ways:

• a dashboard in the Hermes web UI (per-model breakdown + activity over time),
• a /token-saver slash command in the CLI/TUI,
• an optional TUI status widget.

The headline number is your simulated cost — the money that would have been spent if you were paying for this inference. Since your local inference costs you nothing, that number is your savings.

How the numbers are computed

Honesty about the math, because it's the whole point:

• Input / output tokens are read from your provider's usage block. For OpenAI-compatible endpoints (Ollama, LM Studio, vLLM, llama.cpp, …) that field is usually absent, so the plugin estimates tokens from byte length (a tokenizer-based fallback). Your configured provider: local is the trigger for this estimation — hosted providers that report real usage (e.g. OpenRouter, Anthropic, OpenAI) are recorded but not double-counted.
• Prices come from the live OpenRouter model catalog. Unknown/local-only models fall back to a built-in table (Claude, GPT, Gemini, Grok, DeepSeek, Qwen, Llama, …).
• The activity chart prices each time slot using the measured input:output ratio of the whole session (rather than a fixed 60/40 guess), so per-slot cost tracks how you actually use the model.
• Everything is a simulation — it is never billed, and it does not replace your provider's real usage. It is a yardstick.

Install

You need Hermes Agent already installed. There are no Python dependencies to install (stdlib only) and nothing to compile — the dashboard ships as plain JS.

Option A — one command (recommended)

hermes plugins install Hiutaky/token-saver
hermes plugins enable token-saver

hermes plugins install <owner/repo> clones the repo into ~/.hermes/plugins/ and hermes plugins enable adds it to your plugins.enabled allow-list (Hermes only loads plugins that are explicitly enabled).

Option B — manual clone

git clone https://github.com/Hiutaky/token-saver ~/.hermes/plugins/token-saver

then enable it:

hermes plugins enable token-saver

…or add it to ~/.hermes/config.yaml:

plugins:
  enabled:
    - token-saver

Restart

Hermes loads plugins at startup. Restart your Hermes session (or run hermes dashboard again) after installing so the tracker starts.

Updating later: hermes plugins update token-saver (or git pull in the clone). If you previously used the plugin under its old name (token-cost), its data is carried over automatically on first start — nothing to migrate by hand.

Use it

The dashboard (the good part)

Open the Hermes web dashboard (hermes dashboard) and find the Token Saver tab. It shows:

• Total — tokens in your session, the simulated (saved) cost, and the estimated split into prompt vs completion tokens.
• Savings by model — a table per model with OpenRouter $ / 1M in / out and the simulated cost each model "would have cost".
• Activity over time — a bar chart of token usage, bucketed by hour while a session is young and by day once it spans more than a day. Each bar is priced with the session's measured input:output ratio. A grey "earlier" bar holds any usage outside the recent window, and a Total row ties the bars back to the headline number.

The slash command

/token-saver           # live session report
/token-saver refresh   # re-fetch OpenRouter prices now

The TUI status widget (optional)

A compact status card that shows your current simulated savings live in the TUI dock. The plugin ships it bundled (tui-widget/token-saver.mjs) and installs it into ~/.hermes/tui-widgets/ automatically on startup — no configuration needed (the Hermes TUI hot-loads that directory). In the TUI, run:

/token-saver          # dock the panel

The widget reads the local loopback snapshot served by the plugin (127.0.0.1:8791) — no data ever leaves your machine.

Where data lives

• Session state & snapshot: ~/.hermes/plugin-data/token-saver/ (state.json = current session aggregates, snapshot.json = the loopback snapshot the widget/dashboard can read).
• Pricing cache: ~/.hermes/plugin-data/token-saver/pricing.json (live OpenRouter prices, refetched after 72h).

All of it is on your own disk. The plugin opens a loopback-only HTTP endpoint (127.0.0.1:8791) for the UI; it is not reachable from the network. No API keys, no credentials, no connection strings — the only network call it makes is a public GET to OpenRouter's public pricing catalog.

Uninstall

hermes plugins remove token-saver

This removes the plugin and its ~/.hermes/plugin-data/token-saver/ data. Removing the widget is just deleting the widgets.token-saver line from your config.

How it fits in Hermes

• It hooks post_api_request to capture usage (read-only; it never modifies your requests or responses).
• It declares its own plugin.yaml + register(ctx) (native plugin) and ships a dashboard UI under dashboard/ plus an optional TUI widget.
• Because it only uses the Python standard library, there are no dependencies to break and nothing for Hermes to auto-install.

MIT licensed. Do whatever you want with it — just tell us if you build something cool with it.

Project layout

token-saver/
├── plugin.yaml          # native plugin manifest (hooks, command, deps)
├── __init__.py          # tracker: post_api_request hook, loopback bridge,
│                        #   /token-saver command, state persistence
├── pricing.py           # OpenRouter live pricing + built-in fallback table
├── tui-widget/
│   └── token-saver.mjs  # optional TUI dock card (auto-installed to tui-widgets/)
├── dashboard/
│   ├── manifest.json    # dashboard tab (id, title, icon)
│   ├── index.js         # the tab UI (plain IIFE, no build step)
│   ├── style.css        # per-plugin styles
│   └── plugin_api.py    # FastAPI router mounted at /api/plugins/token-saver/
├── README.md
├── LICENSE
└── .gitignore

Questions, ideas, or a different local stack? Open an issue on Hiutaky/token-saver or ping us on the Nous Research Discord (#plugins-skills-and-skins). ★