Hermes

Beta

The Hermes adapter is beta, version 0.1.0. It has passed full internal testing but is not yet validated against a live Hermes install. Live smoke-testing is the remaining gate before stable.

Hermes runs Token Optimizer through a read-only adapter. It scores quality from a three-signal subset, fires a one-line context nudge before each turn, and never writes to the Hermes session database. The narrower feature set follows directly from what Hermes exposes to plugins.

Supported surfaces

Hermes has two entry points into the same adapter.

Surface	How to use
/token-optimizer	Slash command inside a Hermes session. Prints a token and cost summary for recent sessions.
hermes token-optimizer	Shell subcommand. Opens the dashboard at http://localhost:24844.

Install and allow-list from the Hermes install page. The cross-platform grid is at /reference/capability-matrix/.

Three-signal quality score

Hermes scores quality from three signals rather than the seven on Claude Code. Three upstream signals are dropped, each for a concrete data reason.

Signal	Weight	What it measures
Context usage	40%	Latest provider-reported prompt tokens over the model context window; omitted when unavailable
Message-count risk	35%	Session length against a risk curve
Output / input ratio	25%	Productivity, output tokens over input tokens

Three signals are omitted on purpose.

• Cache hit rate is dropped because cache_read_tokens is documented as unreliable in the Hermes schema.
• Compaction depth is dropped because successful compaction counts are not persisted. Current Hermes rows do expose failure, fallback, cooldown, ineffective-count, and recovery fields, which Token Optimizer uses for compression-health gating.
• API calls per turn is dropped because the figure is not directly comparable across Hermes sessions.

Pre-turn context nudge

The nudge fires through the pre_llm_call hook before each turn. Hermes owns compression. 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 fire at roughly 70 percent usage and escalate at 85 percent. It fires at most once per session and does not re-arm: a later drop back under the threshold and a second crossing stay silent.

The numerator uses provider-reported prompt tokens from the latest request. 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. Displays mark any locally estimated numerator with ~; cumulative session token totals are never used as occupancy.

Read-only by design

The adapter opens ~/.hermes/state.db with a read-only, immutable URI and PRAGMA query_only = ON. It never writes back. All plugin hooks are wrapped so no exception escapes into the Hermes host. There is no telemetry and there are no network calls. There is nothing to disable for safety, because the adapter only reads.

Conservative per-model savings

Cost and savings figures use the Hermes-reported cost when available and fall back to a Token Optimizer estimate otherwise. Estimates are deliberately conservative, since Hermes does not expose every field a precise figure would need.

Features not available

Several features depend on hooks Hermes does not provide.

Feature	Reason
Smart Compaction with PreCompact/PostCompact	Hermes has its own native compressor but exposes no pre/post compression plugin hooks; Token Optimizer is observational and only injects a fallback nudge via pre_llm_call
Status line quality bar	No terminal status-bar surface
Quality Nudges as active injection	No UserPromptSubmit equivalent; limited to pre_llm_call
Keep-Warm, delta read, structure map, bash compression	Not available
Fleet Auditor direct scan	Fleet Auditor covers Claude Code and Codex; Hermes data flows to the shared trends database and is read through its own dashboard

Runtime prefix

Hermes commands run through measure.py with the hermes- subcommand names.

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

If Hermes is not at ~/.hermes, set HERMES_HOME ahead of the command. See the configuration reference.

Doctor command

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

It checks HERMES_HOME resolution, the plugin directory and required files, declared hooks, a bridge smoke test, the plugins.enabled activation entry, state.db readability, and dashboard-port availability.

Dashboard

The Hermes dashboard serves at http://localhost:24844. It is the shared Token Optimizer dashboard populated with Hermes session data across the Overview, Quality, Waste, Sessions, and Daily tabs.