hermes-flash-kit

A harness, cost and orchestration kit for Hermes Agent running on cheap models such as GLM 5.3 Flash and DeepSeek V4 Flash through the Nous Portal. The audits, plans, patches, runner and measurement harness were built in one day (2026-09-17) by a Claude Fable 5.1 session driving Claude Code: six read-only audits, five plans, then the code, then a measured before-and-after. The proxy is older: v1.0 predates that day and v1.1 (the version shipped here) was built on it that day. The case study with the two HTML reports is at https://ml0x.com/case-studies/hermes-glm-5-3-flash/.

The problem it solves: a Hermes install on flash-class models that burned its budget on 90k-token prompts, subagents that died at the iteration cap with nothing written, a proxy ledger that over-counted the bill by an order of magnitude, and long-running "goal" sessions with no pass condition.

Headline numbers (one install, one day, measured from the ledger and state.db)

what	before	after
ledger vs the real portal bill	17x too high (upstream usage.cost was a flat 0.00005 per call in our measurements; cache reads billed at full rate)	within 1.1 percent of the portal's own spend figure on a 265-call window, after cache-aware pricing and a rebase to real dollars
median prompt size	89,965 tokens	32,707 tokens
one pipeline run, through to publication	$0.311 over 315 calls for a morning run on one site	$0.168 over 286 calls for a run on another site that went through to publication (both at catalog rates from the same ledger)
compaction trigger	153k tokens (the 75 percent floor on a 202k window)	51k tokens
cap stops mid-task	several per day at a phantom ceiling	zero after rebasing caps to real dollars

What is in the box

directory	contents
modellock/	proxy.py v1.1, the fail-closed model-lock proxy: allow-list, USD caps (lifetime, daily, per-model, per-bucket, portal reserve), cache-aware pricing, reasoning overrides, timeouts, degrade lane. Plus policy.example.json, upstream.env.example, a launchd plist, newsyslog rotation and an acceptance test with a mock upstream.
hermes-config/	the recommended config.yaml keys with the measured reason for each, the budget_gate.py pre_tool_call hook, the delegation-contract skill and its one-line SOUL.md rule.
patches/	five unified diffs against the Hermes source (exit reasons, child deliverable contract, busy-parent steer drain, curator 60-char rule, verify-on-stop scope) and REAPPLY.md for after hermes update.
measure/	measure.py, compare.py, after.sh: the read-only acceptance harness over the ledger, proxy log, state.db and agent.log, scored against twelve criteria. Also the comment-preserving apply_tuning.py and setkey.py.
runner/	the pipeline runner: one Hermes profile per pipeline, one hermes -p pl-<name> chat -q per step, a script gate per step, exit 75 for retry-later, cost per step from the ledger, a launchd template. Includes the two-step smoke pipeline.
docs/	a pointer to the public case study, where the audits and plans this was built from are summarised.

Ten-minute quickstart

Assumes Hermes Agent is installed at ~/.hermes on macOS and you have a Nous inference key.

1. Proxy. mkdir -p ~/.hermes/modellock && cp modellock/proxy.py ~/.hermes/modellock/. Copy modellock/upstream.env.example to ~/.hermes/modellock/upstream.env, fill in the key, chmod 600 it.
2. Policy. cp modellock/policy.example.json ~/.hermes/modellock/policy.json. Set caps.total_usd and caps.daily_usd to what your balance can lose. Start it: sed "s|__HOME__|$HOME|g" modellock/com.example.hermes-modellock.plist > ~/Library/LaunchAgents/com.example.hermes-modellock.plist && launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.hermes-modellock.plist, then curl -s 127.0.0.1:8788/healthz.
3. Point Hermes at it: a custom provider with base URL http://127.0.0.1:8788/v1, any non-empty API key, model z-ai/glm-5.3-flash (or the alias glm).
4. Config keys. Back up ~/.hermes/config.yaml, then either merge hermes-config/config.recommended.yaml by hand or run ~/.hermes/hermes-agent/venv/bin/python measure/apply_tuning.py ~/.hermes/config.yaml.
5. Hook and skill. cp hermes-config/budget_gate.py ~/.hermes/hooks/; register it as a pre_tool_call hook for delegate_task. mkdir -p ~/.hermes/skills/software-development/delegation-contract && cp hermes-config/delegation-contract.SKILL.md ~/.hermes/skills/software-development/delegation-contract/SKILL.md; append hermes-config/SOUL.md.rule to ~/.hermes/SOUL.md.
6. Measure. python3 measure/measure.py now, write the apply time into measure/apply_time_wave1.txt, restart your Hermes sessions, and run bash measure/after.sh two hours later. See measure/README.md.

Optional: apply patches/ to ~/.hermes/hermes-agent (see patches/REAPPLY.md) and run a pipeline with runner/ (see runner/README.md; start with smoke).

Safety notes, read before relying on any of it

• The L12 human-signoff gate described in the case study is instruction-level: an agent can be told not to write the approval token, but only a file the agent cannot write (owned by another user, or outside its sandbox) actually enforces it.
• Claude Code print mode kills subagent phases after 600 seconds unless CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0 is set; the audits behind this kit were produced with it set.
• Hermes's own auth code comments say Nous refresh tokens are single-use. The proxy therefore reads the access token from auth.json and never refreshes it; if a second client refreshes, the first is logged out. Do not add a refresh call.
• The portal reserve reads the account balance from the portal's /api/oauth/account endpoint, which is what the Hermes client itself calls. It is not a documented public API and may change without notice; if it does, the proxy falls back to the ledger and caps alone.
• The proxy binds to loopback with no authentication of its own. The caps are checked before each call, so the call that crosses a cap still completes (worst case one call at per_call_max_tokens).
• tests/acceptance.sh copies your live auth.json and upstream.env into a sandbox under /tmp. Delete it after.
• Everything here was measured on one install for one day. The rates in policy.example.json and measure.py are the catalog prices on 2026-09-17; re-read them with python3 proxy.py --refresh-rates before trusting a bill.

Attribution

Hermes Agent is by Nous Research; models are served through the Nous Portal. This kit is an independent set of scripts and notes. Not affiliated with Nous Research, Z.ai, DeepSeek or Anthropic. Built by a Claude Fable 5.1 session in Claude Code, operated by theluckystrike. MIT licensed, see LICENSE. Security notes in SECURITY.md, history in CHANGELOG.md.