Hermes (beta)

Token Optimizer for NousResearch Hermes adds per-turn usage capture, cost tracking, context-quality scoring, a proactive pre-turn context nudge, and the shared dashboard. It reads from Hermes’s own ~/.hermes/state.db with read-only access; it never writes back.

Prerequisites

NousResearch Hermes installed
Python 3.x or later
Git

Recommended method: clone and install

Clone the repo:

git clone https://github.com/alexgreensh/token-optimizer.git

Run the installer:
Terminal window
```
token-optimizer/install.sh --hermes
```
The installer copies the plugin payload into ~/.hermes/plugins/token-optimizer/. Hermes discovers plugins from that directory automatically.
Allow-list the plugin. Add this to ~/.hermes/config.yaml:
```
plugins:
  enabled:
    - token-optimizer
```
Alternatively, pass --enable to the installer and it adds the entry automatically:
Terminal window
```
python3 token-optimizer/skills/token-optimizer/scripts/measure.py hermes-install --enable
```
--enable is idempotent and backs up your config before touching it.

Preview what the installer will write without making any changes:

token-optimizer/install.sh --hermes --dry-run

If your Hermes home is not at ~/.hermes, set HERMES_HOME before running:

HERMES_HOME=/path/to/.hermes python3 token-optimizer/skills/token-optimizer/scripts/measure.py hermes-install

The install is idempotent. Re-running replaces files in place without touching other plugins or state.

Verify the install

python3 token-optimizer/skills/token-optimizer/scripts/measure.py hermes-doctor

hermes-doctor checks: HERMES_HOME resolution, plugin directory presence, required files (manifest and all runtime modules), declared hooks, bridge smoke test, the plugins.enabled entry in config.yaml, state.db readability, and dashboard port availability.

A healthy install passes all checks.

Dashboard

URL: http://localhost:24844

The Hermes dashboard uses the same shared Token Optimizer template (Overview, Quality, Waste, Sessions, Daily tabs) populated with Hermes session data. Open it with the CLI subcommand from your shell:

hermes token-optimizer

Pass --port <n> to override the default port.

Inside Hermes

Surface	How to use
`/token-optimizer`	Slash command inside any Hermes session. Prints token and cost summary for recent sessions.
`hermes token-optimizer`	CLI subcommand from your shell. Opens the dashboard at `http://localhost:24844`.

A context nudge fires automatically before each turn via the pre_llm_call hook. Hermes owns compression, so Token Optimizer stays silent while the native compressor is enabled and healthy. If native compression is disabled, failed, or ineffective, a one-line notice can appear at approximately 70% context usage and escalate at 85% or higher. It fires at most once per session and does not re-arm within that session.

The latest provider-reported prompt size is the occupancy numerator. Hermes does not expose the live context-window size to plugins, so the denominator is a mapped model window or a 200,000-token fallback. Cumulative session totals are never used as occupancy.

Auto-update

Manual only. After pulling new changes:

git pull
token-optimizer/install.sh --hermes

Uninstall

Run the uninstaller:

token-optimizer/install.sh --hermes --uninstall

Remove the allow-list entry from ~/.hermes/config.yaml:

plugins:
  enabled:
    # remove: - token-optimizer

Known gaps

These features are not available on Hermes due to the plugin API surface:

Smart compaction with PreCompact and PostCompact hooks: no such hooks exist in Hermes; Token Optimizer provides a pre-turn nudge via pre_llm_call instead
Quality status bar: no terminal status bar surface in Hermes
Fleet Auditor: does not scan Hermes sessions directly; Hermes data flows into the shared trends.db and is accessible via the Hermes dashboard
Keep-Warm automation, Delta read substitution, Structure Map, Bash output compression: not available
Quality nudges via UserPromptSubmit: Hermes has no equivalent hook; nudges use pre_llm_call only

See Hermes capabilities for the full feature list, the 3-signal quality scoring subset, and data privacy details.