All plugins

hermes-subscription-meter

Provider-neutral subscription quota matrix panel — each provider's subscription window as a single time x quota row (elapsed vs remaining at a glance), with UI-side show/hide per provider row. Disclosure — reads provider keys from the current profile's .env and token presence from its auth.json, and calls each provider's own usage/balance API with that key (Kimi, GLM, MiniMax, Command Code, DeepSeek, xAI management, OpenRouter, Alibaba Cloud BSS, Grok, Codex via Hermes); an optional shared_sources setting reads another profile's .env/auth.json the same way; the token-activity heatmap reads per-day token totals, providers and model names from the state.db of this profile and of every other profile on the install (read-only, no message content, nothing leaves the machine); nothing is written outside this plugin's settings.

NealZhouPandaDesktopv0.7.0Updated 12 days ago

About

Provider-neutral subscription quota matrix panel — each provider's subscription window as a single time x quota row (elapsed vs remaining at a glance), with UI-side show/hide per provider row. Disclosure — reads provider keys from the current profile's .env and token presence from its auth.json, and calls each provider's own usage/balance API with that key (Kimi, GLM, MiniMax, Command Code, DeepSeek, xAI management, OpenRouter, Alibaba Cloud BSS, Grok, Codex via Hermes); an optional shared_sources setting reads another profile's .env/auth.json the same way; the token-activity heatmap reads per-day token totals, providers and model names from the state.db of this profile and of every other profile on the install (read-only, no message content, nothing leaves the machine); nothing is written outside this plugin's settings.

hermes-subscription-meter

A subscription-quota dashboard plugin for Hermes Agent. This is not a progress bar: quota is measured in time and drawn as a cell matrix, so how much you have used and how much is left is obvious at a glance, and the color shift tells you the current quota status. The board reads in three zones: the weekly zone (84 cells, 7 days × 12 a day, with the 5-hour window overlaid on it), a divider, the monthly zone for plans that also cap a month (8-hour cells, 3 a day — a 30-day month is 90 cells), a divider, and the balance zone for prepaid accounts. When choosing is hard, the plugin automatically ranks the model it suggests you use first for the problem at hand at the top.

Under the board sits a sale ticker: the models the Nous Portal is currently discounting or giving away, scrolling past with their current price and the original struck through.

Provider visibility is controlled from the UI — show or hide each provider yourself, no config-file edits.

Screenshot

Time × quota matrix: one provider per row

Install

One installer, both halves: the agent-side backend (plugin.yaml + __init__.py + dashboard/)
and the desktop panel (desktop/plugin.js). In the Hermes desktop app, open
Settings → Plugins → Install from Git and enter:

NealZhouPanda/hermes-subscription-meter

Or from the CLI:

hermes plugins install NealZhouPanda/hermes-subscription-meter

The app copies the desktop half into its own plugin folder. If the panel does not appear,
restart the Hermes desktop app or press Rescan on the Plugins page. Both halves ship
switched off — turn the plugin and its desktop panel on in Plugins; the panel then docks as
a bottom pane, with a sidebar page and a ⌘K command.

Supported providers

The discovery layer collects candidate credentials from the Hermes provider registry, the current profile's logged-in OAuth (auth.json) and configured environment slots, then picks a fetcher by rule:

| Provider | Source |
|---|---|
| Codex (ChatGPT) | Hermes account_usage, fallback to chatgpt.com usage endpoint |
| GLM (Zhipu) | open.bigmodel.cn quota endpoint |
| Kimi (Moonshot) | api.kimi.com coding usage endpoint |
| Command Code | api.commandcode.ai /alpha/billing/credits (5h + weekly windows) + /alpha/billing/subscriptions (monthly quota, reset on the billing period) |
| DeepSeek | api.deepseek.com balance + platform cost |
| xAI (Grok subscription) | Hermes account_usage (xai-oauth), fallback to CLI proxy billing |
| MiniMax | CN plan usage endpoint |
| Qwen (DashScope) | Alibaba Cloud balance API |
| Nous | Hermes account_usage |
| OpenRouter | openrouter.ai /credits prepaid balance (a plain sk-or- key is enough) |

Anything detected but lacking a fetcher is shown as no_fetcher rather than silently dropped. Quota windows and prepaid balances are both supported; unrecognized credentials are labeled instead of guessed at.

DeepSeek: the balance needs only the API key

DEEPSEEK_API_KEY on its own is enough for the balance row. The TODAY / 7D / 30D
spend columns come from a second, separate endpoint and additionally need
DEEPSEEK_PLATFORM_TOKEN — the userToken of your own logged-in session on
platform.deepseek.com — in the current profile's .env. Without it the row still
renders and only those three columns stay blank, and the Plugins page reports the
provider as Partial data available. The token expires with the web session; refresh
it when the spend columns go blank again. Nothing else about the provider depends on it.

How it works

  • desktop/plugin.js — the desktop panel: the weekly matrix (84 cells) with the 5-hour lock overlay, the monthly zone (8-hour cells, sized to the length of the current month), balance bars, automatic ranking of the model it suggests you use first, per-provider visibility toggles, and a sale ticker under the board (current price against the struck-through original, free models, and a per-provider switch). A monthly quota is shown by default when detected; the provider-specific switch can hide it.
  • dashboard/plugin_api.py — a FastAPI router that turns credentials into provider-neutral quota rows. Secrets stay in memory only; they never appear in API responses, logs or error strings.
  • tests/ — 209 frontend tests (node:test) + 165 backend tests (pytest).

Development

Frontend tests (no dependencies, Node ≥ 18):

node --test tests/*.test.mjs

Backend tests (requires fastapi, pydantic; run from the repo root):

python -m pytest tests/

The backend test suite runs fully offline: every test gets a temp HERMES_HOME and outbound sockets are blocked by fixtures in tests/conftest.py.

Deploying the panel into a running Hermes goes through the guard instead of a
plain copy — it checks syntax, runs the frontend suite, keeps the previous build
as .last-good, replaces the live file atomically (a half-written file would be
executed by the app's directory watcher), then watches the app log for a few
seconds and rolls back by itself if this plugin starts throwing:

node tools/deploy.mjs        # deploy + watch; add --no-sentinel to skip the watch
node tools/rollback.mjs      # put the previous build back by hand

docs/dev/ contains the design-review notes from the provider-neutral refactor. diagnostics/ holds small local debugging scripts used during development.

Contact

Questions / issues / collaboration: nealzhou.panda@gmail.com

License

MIT © 2026 Neal Zhou

A Chinese README (README.zh-CN.md) may be added later.

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