All plugins

token-stats

Lifetime token usage page for Hermes Desktop: totals across every profile on the connected (local or remote) gateway, a per-model table (share, input/output, cache read and cache %, calls, tokens per call, measured speed, cost), API-equivalent cost and savings from free models, subscription plans and prompt caching, a provider and profile split, activity streaks and month-over-month trend, daily chart, and top tools, skills and background (aux) work; plus a status-bar lifetime chip. Disclosure — read-only: calls the gateway's /api/analytics/models and /api/analytics/usage routes for each profile through the raw window.hermesDesktop.api bridge (no typed SDK helper exists for them), lists profiles and connections, and listens to message/usage events to time turns. Stores speed samples, a pruning ledger (so lifetime totals survive sessions.auto_prune) and the last loaded numbers in plugin storage, and reads an optional user-made archive.json from its own ctx.files data folder. Cost uses a bundled snapshot of models.dev list prices. No network calls of its own, no telemetry, no credentials.

amitamit10Desktopv1.0.0Updated 3 days ago

About

Lifetime token usage page for Hermes Desktop: totals across every profile on the connected (local or remote) gateway, a per-model table (share, input/output, cache read and cache %, calls, tokens per call, measured speed, cost), API-equivalent cost and savings from free models, subscription plans and prompt caching, a provider and profile split, activity streaks and month-over-month trend, daily chart, and top tools, skills and background (aux) work; plus a status-bar lifetime chip. Disclosure — read-only: calls the gateway's /api/analytics/models and /api/analytics/usage routes for each profile through the raw window.hermesDesktop.api bridge (no typed SDK helper exists for them), lists profiles and connections, and listens to message/usage events to time turns. Stores speed samples, a pruning ledger (so lifetime totals survive sessions.auto_prune) and the last loaded numbers in plugin storage, and reads an optional user-made archive.json from its own ctx.files data folder. Cost uses a bundled snapshot of models.dev list prices. No network calls of its own, no telemetry, no credentials.

Token Stats — Hermes Desktop plugin

Lifetime token usage for Hermes Desktop: where your tokens went, which models
ate them, how fast they ran, and what they would have cost.

Token Stats overview: lifetime total, summary cards, highlights and savings

Open it from the Token Stats sidebar row, the Σ 7.6B tok chip in the
status bar, or ⌘K → Token Stats: open lifetime usage.

What it shows

  • Lifetime total (input + output + cache read), with reasoning broken out
    and a share bar per model. Switch between 7d / 30d / 90d / Lifetime and
    between All profiles on the gateway or This profile.
  • Summary cards: sessions, API calls, models used, average tokens per
    session, average speed, cost, savings and cache hit rate.
  • Highlights: most tokens, most API calls, fastest model, highest cost.
  • Per-model table: share, tokens, in/out, cache read, cache %, calls,
    tokens per call, measured speed, sessions and cost. Hover any cell for exact
    numbers.
  • Savings: what your usage is worth at metered API list prices, split into
    free models (valued at their paid sibling), subscription plans (OAuth
    providers such as Codex that bill nothing per token) and prompt caching.
  • By provider, by profile and activity: active days, current and
    longest streak, busiest day, this month vs last month with a projection,
    and a weekday chart.
  • Daily usage chart (input, output, cache).
  • Top tools, top skills and background work (compression, titles,
    vision… the aux tasks Hermes runs on your behalf).

Per-model table with share, cache %, calls and tokens per call

Top tools, skills, background work and the per-profile split

Where the numbers come from

  • Tokens, sessions, calls, tools and skills come from the connected
    gateway's own analytics routes (/api/analytics/models and
    /api/analytics/usage), so they work the same against a local or a remote
    gateway. Hermes caps those windows at 365 days.
  • Speed is not stored by Hermes. The plugin records the average
    tokens/second and latency the gateway reports at the end of every turn,
    and times turns itself for providers that report none (first streamed
    token → message.complete). It fills in as you chat; ⌘K → Token Stats:
    reset recorded speed samples
    clears it.
  • Cost uses Hermes's recorded billed cost when there is one. Otherwise it
    prices the tokens with a snapshot of models.dev list
    prices (first-party provider preferred; -thinking/-high/size variants
    fall back to the base model). Plan fees are not subtracted, so "saved" is
    an upper bound.

Lifetime past pruning

A gateway with sessions.auto_prune: true deletes ended sessions after
retention_days, and their usage leaves the database with them. Token Stats
keeps a small ledger in plugin storage: whenever a model's total drops, the
missing amount is banked, so the lifetime figure never goes down while the app
is open.

To bring back usage that was pruned before you installed the plugin, build an
archive.json from old state.db backups (Hermes writes them under
state-snapshots/ before updates and under profiles/.deleted/ when a profile
is removed):

python3 scripts/export-pruned.py \
  --live ~/.hermes/state.db \
  --backup '~/.hermes/state-snapshots/*/state.db' \
  --backup '~/.hermes/profiles/.deleted/*/*/state.db' \
  --connection my-server.example.com > archive.json

The script opens every database read-only and only exports sessions that are
missing from the live one, so nothing counts twice. Put the result in the
plugin's data folder (<Hermes Desktop user data>/plugin-files/data/token-stats/archive.json,
for example ~/.config/Hermes/plugin-files/data/token-stats/ on Linux). It is
added to All profiles · Lifetime on the connections you list (omit
--connection to apply it everywhere).

Privacy and behaviour

  • Reads only: the gateway analytics routes, the profile list, the connection
    list (to match archive.json to a connection) and live gateway usage
    events. It never writes to the gateway.
  • Stores speed samples, the pruning ledger and the last loaded numbers in
    plugin storage on this machine. It reads archive.json from its own data
    folder if you put one there.
  • No network calls of its own, no telemetry, no credentials.
  • REST calls go through window.hermesDesktop.api with the active
    connection's routing (the SDK has no typed helper for the analytics routes
    yet).

Install

hermes plugins install token-stats

Or copy desktop/plugin.js to ~/.hermes/desktop-plugins/token-stats/plugin.js;
the app loads it within a few seconds.

Layout

  • desktop/plugin.js — the plugin. Plain ESM; imports only
    @hermes/plugin-sdk, react and react/jsx-runtime. No build step.
  • scripts/export-pruned.py — optional backup → archive.json exporter.
  • plugin.yaml — the manifest the catalog and hermes plugins read.

License

MIT

README from the reviewed commit cef5577; it updates when the author re-pins.

More by amitamit10

3 plugins by amitamit10 in the catalog.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section