Hermes is the agent that grows with you. It lives on your server, remembers what it learns, and gets more capable the longer it runs. That's the upside.
The flip side is that an agent designed to run continuously for weeks or months can also see token spend drift for weeks or months. Most teams will not notice until the invoice shows up.
Persistent agents need persistent guardrails. Revenium for Hermes adds real-time budget enforcement to any Hermes agent, so token usage is capped before it gets expensive, not after.
How to Install Revenium for Hermes
Installing the Revenium skill for Hermes takes three commands:
hermes skills tap add revenium/hermes-revenium
hermes skills install revenium/hermes-revenium/skills/revenium --force
bash ~/.hermes/skills/revenium/scripts/install-cron.sh
A word on the --force flag: Hermes ships an install-time scanner that correctly flags this skill as DANGEROUS because it installs a per-minute crontab entry. That's the scanner doing its job. The cron is required for metering to work, and we'd rather be honest about why it's there than pretend it isn't. You can read every script before you run it. This is a feature of Hermes' security posture, not a footnote we wish weren't there.
On first use, the skill walks you through an interactive setup:
- Revenium API key, Team ID, Tenant ID, User ID
- Optional organization name for attribution in Revenium reporting
- Budget amount and period (DAILY / WEEKLY / MONTHLY / QUARTERLY)
- Whether the agent runs autonomously, and which Hermes messaging channel should receive halt notifications such as Slack, Discord, Telegram, WhatsApp, Signal, Email, or CLI
After that, every Hermes session becomes budget aware. The skill runs silently in the background and stays out of your way until it needs to protect you. It meters real consumption, compares it to thresholds, and halts before the limit is crossed rather than after. In autonomous mode, a hard halt fires and sends a notification on your configured channel. The halt persists until someone clears it. A budget breach should require a human decision and should not quietly resolve itself.
Why Persistent Agents Need This More, Not Less
Hermes' selling point is duration. It's designed to run for weeks. It runs scheduled cron jobs unattended. It delegates to subagents that have their own conversations and terminals. Every one of those properties — persistence, autonomy, parallelism — also compounds spend if it's ungoverned.
Subagents are the failure mode most teams miss. A parent agent might be well-behaved, but a subagent spawned in a Python RPC pipeline with its own context window can quietly burn tokens for hours. Revenium meters at the SQLite layer (~/.hermes/state.db), so subagent activity is captured the same as the parent's. You don't need to instrument them individually.
The longer Hermes runs, the more it should know about your projects and the more your finance team should know what it cost.
How It Works
The skill is a single file
The guardrail is one Markdown file — SKILL.md — that Hermes loads at session start. No SDK integration. No application refactors. No changes to your agent runtime. The skill carries its own instructions and operational logic. After install, a one-time cron-installer script handles the parts Hermes can't do itself, because Hermes deliberately doesn't grant skills crontab access. That's another scanner-positive design choice, and a good one.
Think of it like the meter on the side of your house. It measures what flows through the pipes, but it never shuts off your faucets. Budget enforcement should work the same way. It should give visibility and control without brittleness.
Budget checks at the boundary
Before each operation — response, tool call, exploration — the skill reads ~/.hermes/state/revenium/budget-status.json:
- Within budget → proceed silently
- Exceeded, interactive → warn and ask
- Exceeded, autonomous → hard halt + notify on configured Hermes channel
- Status file missing → fail-open with a warning
The local-file read adds no network latency per turn. The budget check is fast. clear-halt.sh tokens are tagged as GUARDRAIL operations in Revenium, so enforcement overhead is tracked separately from real work.
Metering in the background
Here's where the Hermes integration differs technically from our other skills: Hermes stores session activity in a SQLite database (~/.hermes/state.db) rather than JSONL files. Same idea, different shape.
The metering reporter reads token usage from SQLite, computes deltas against an idempotency ledger keyed HERMES:<session_id>:<total_tokens>, and ships each delta to Revenium via revenium meter completion. The per-event payload includes:
- Input/output token counts
- Model identifier and provider
- Request/response timestamps and computed duration
- Session ID for correlation
- Optional organization name for attribution
- Operation type tagging (
CHAT,TOOL_CALL,GUARDRAIL)
Metering is out-of-band, which means zero impact on agent execution. The agent runs fast. Accounting catches up within a minute. For an agent designed to run for weeks, one minute of accounting lag is invisible.
Fail-open behavior
Hermes is a long-running agent. The last thing you want is an unrelated cron hiccup at 3am bricking a scheduled briefing. If budget-status.json is missing or stale, the skill surfaces a clear warning — "Budget status not yet available. Proceeding with caution." — and lets the operator decide. Safety shouldn't come at the cost of brittleness.
If you're a first-time installer and see that message, it means the metering cron hasn't been installed yet. It points you straight to install-cron.sh.
The Revenium CLI
Every Revenium skill is backed by the same CLI:
brew install revenium/tap/revenium
Repo: github.com/revenium/revenium-cli
The CLI wraps the Revenium API for budget configuration, alert management, metering ingestion, local state sync, and configuration management. The skill orchestrates it under the hood so conversational users never touch it directly. Inside a Hermes session, /revenium lets you view, reset, and reconfigure.
What's Next: Tool Registry
Token spend and external tool spend live in the same ledger. Every metered event is tagged by operation type — CHAT, TOOL_CALL, GUARDRAIL — so your Hermes token budget breaks down by what the agent was actually doing.
For Hermes, this matters more than for most agents, because Hermes does so much non-LLM work: browser automation, web search, image generation, text-to-speech, multi-model reasoning. The Tool Registry stitches all of that into a single AI operating cost view alongside the token meter. One dashboard. The full picture.
Open Source, Free Tier, Community
The skill is fully open source under the MIT license, and it matches the Hermes license. The Revenium developer tier is free.
We're interested in how teams structure budgets, for example, by project, by user, by environment, by model, or by subagent. If you're running Hermes in production and have opinions, we want to hear them.
Your agent grows with you. Now it stays within its means too.
