Hermes Wiki
Tools/Hermes_Agent

Hermes Agent

A highly customisable, locally-run AI operating system designed for practical task execution. Loads Python plugins at startup, intercepts tool calls before execution, and delegates real work to a configured LLM. Designed for persistent ambient agents running on a VPS — always-on, no GUI required.

[!note] RTK native plugin RTK ships a first-class Hermes plugin (rtk init --agent hermes). It intercepts every terminal tool call, rewrites the command to its RTK equivalent, and the compressed output is what Hermes (and the LLM) actually sees. Zero workflow changes, 60–98% fewer shell-output tokens.

RTK Integration

How it works

Hermes loads plugins from Python at startup. The RTK plugin is a thin Python adapter placed at ~/.hermes/plugins/rtk-rewrite/. When Hermes issues a terminal tool call, the plugin:

  1. Reads the terminal tool payload (the command field)
  2. Calls rtk rewrite (Rust binary) with the command
  3. Mutates the command in-place to the RTK-prefixed version
  4. Hermes executes the rewritten command — agent never knows

All rewrite logic lives in Rust inside rtk rewrite. When RTK adds new compression rules, the Hermes plugin picks them up automatically by delegating to the binary.

Install

# Install RTK first
brew install rtk          # macOS
# or
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

# Install Hermes plugin
rtk init --agent hermes
# Places plugin under ~/.hermes/plugins/rtk-rewrite/
# Enables via plugins.enabled in Hermes config

Fail-open safety

The plugin never blocks command execution. If rtk is missing from PATH, the plugin prints a warning and skips hook registration — Hermes runs normally. Same for any error in rtk rewrite: falls back to the original command unchanged.

Limitations

  • Only terminal tool calls are intercepted; other Hermes tool types pass unchanged
  • Compound shell commands, heredocs, and commands already prefixed with rtk are skipped
  • Shell hooks (.bashrc/.zshrc) are not used — Hermes plugin API only

Why this matters for a VPS ambient agent

A Hermes agent running continuously on a VPS issuing git log --stat -2 hourly:

Raw With RTK plugin
Tokens per call ~8,388 ~108
Tokens per day (24 calls) ~201,312 ~2,592
Savings — 98.7%

At Sonnet 4.6 input pricing that difference compounds significantly across a month of ambient operation. RTK is the highest-ROI first install for any persistent Hermes deployment.

Stack Recommendation

For a Hermes ambient agent on a VPS handling shell tasks + document reads:

Layer 1 (shell output)   → RTK plugin    (rtk init --agent hermes)
Layer 2 (document reads) → Headroom proxy (headroom proxy --port 8787)

headroom wrap hermes gives both layers automatically if Headroom is installed — RTK is bundled as a Headroom dependency.

Hermes Wiki