Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

feat(providers): add Hermes agent wrap support (#934)

Ashish Patel7877241d84c9
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 15f9ffa59..1e60ec0ff 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -14,6 +14,7 @@ Usage:
headroom wrap antigravity # Start proxy + print Antigravity config instructions
headroom wrap grok-build # Start proxy + configure Grok Build
headroom wrap openclaw # Install + configure OpenClaw plugin
+ headroom wrap hermes # Start proxy + Hermes agent
headroom wrap claude --port 9999 # Custom proxy port
headroom wrap claude -- --model opus # Pass args to claude
"""
@@ -177,6 +178,8 @@ from headroom.providers.grok_build.config import (
inject_grok_provider_config,
restore_grok_provider_config,
)
+from headroom.providers.hermes import build_launch_env as _build_hermes_launch_env
+from headroom.providers.hermes import unsupported_provider_error as _hermes_provider_error
from headroom.providers.kimi import build_launch_env as _build_kimi_launch_env
from headroom.providers.mistral_vibe import build_launch_env as _build_mistral_vibe_launch_env
from headroom.providers.omp import build_launch_env as _build_omp_launch_env
@@ -8234,7 +8237,71 @@ def continue_dev(
# =============================================================================
+# Hermes (Nous Research)
+# =============================================================================
+
[email protected](context_settings={"ignore_unknown_options": True})
+@_retired_context_tool_option
+@proxy_port_option()
[email protected]("--code-graph", is_flag=True, help="Enable code graph indexing")
[email protected]("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
[email protected]("--learn", is_flag=True, help="Enable live traffic learning")
[email protected]("--memory", is_flag=True, help="Enable persistent cross-session memory")
[email protected]("--backend", default=None, help="API backend")
[email protected]("--anyllm-provider", default=None, help="Provider for any-llm backend")
[email protected]("--region", default=None, help="Cloud region for Bedrock/Vertex")
[email protected]("--verbose", "-v", is_flag=True, help="Verbose output")
[email protected]("--prepare-only", is_flag=True, hidden=True)
[email protected]("hermes_args", nargs=-1, type=click.UNPROCESSED)
+def hermes(
+ port: int,
+ code_graph: bool,
+ no_proxy: bool,
+ learn: bool,
+ memory: bool,
+ backend: str | None,
+ anyllm_provider: str | None,
+ region: str | None,
+ verbose: bool,
+ prepare_only: bool,
+ hermes_args: tuple,
+) -> None:
+ """Launch the Hermes agent through the Headroom proxy."""
+ if prepare_only:
+ return
+
+ hermes_bin = shutil.which("hermes")
+ if not hermes_bin:
+ click.echo("Error: 'hermes' not found in PATH.")
+ click.echo("Install Hermes: https://hermes-agent.nousresearch.com/")
+ raise SystemExit(1)
+
+ provider_error = _hermes_provider_error(hermes_args)
+ if provider_error:
+ click.echo(provider_error)
+ raise SystemExit(1)
+
+ env, env_vars_display = _build_hermes_launch_env(port, os.environ)
+ _launch_tool(
+ binary=hermes_bin,
+ args=hermes_args,
+ env=env,
+ port=port,
+ no_proxy=no_proxy,
+ tool_label="HERMES",
+ env_vars_display=env_vars_display,
+ learn=learn,
+ memory=memory,
+ agent_type="hermes",
+ code_graph=code_graph,
+ backend=backend,
+ anyllm_provider=anyllm_provider,
+ region=region,
+ )
+
+
+# =============================================================================
# OpenClaw
# =============================================================================
diff --git a/headroom/providers/hermes.py b/headroom/providers/hermes.py
index 2538dfdcf..edf2e2574 100644
--- a/headroom/providers/hermes.py
+++ b/headroom/providers/hermes.py
@@ -9,8 +9,13 @@ from __future__ import annotations
import json
import logging
+import os
+from collections.abc import Mapping
from typing import Any
+from headroom.providers.claude import proxy_base_url as claude_proxy_base_url
+from headroom.providers.codex import proxy_base_url as codex_proxy_base_url
+
logger = logging.getLogger("headroom.providers.hermes")
_CHAT_ROLES = frozenset({"user", "assistant"})
@@ -22,6 +27,53 @@ _CODEX_RESPONSES_SUFFIX = "/v1/responses"
_CLAUDE_MESSAGES_SUFFIX = "/v1/messages"
+def build_launch_env(
+ port: int, environ: Mapping[str, str] | None = None
+) -> tuple[dict[str, str], list[str]]:
+ """Build the environment used to route the Hermes CLI through Headroom."""
+ env = dict(environ if environ is not None else os.environ)
+ openai_base_url = codex_proxy_base_url(port)
+ anthropic_base_url = claude_proxy_base_url(port)
+ env["OPENAI_BASE_URL"] = openai_base_url
+ env["ANTHROPIC_BASE_URL"] = anthropic_base_url
+ return env, [
+ f"OPENAI_BASE_URL={openai_base_url}",
+ f"ANTHROPIC_BASE_URL={anthropic_base_url}",
+ ]
+
+
+# Hermes honors OPENAI_BASE_URL / ANTHROPIC_BASE_URL only for these providers.
+# Its default (openrouter) and others such as nous call their own endpoints.
+_ROUTED_PROVIDERS = frozenset({"anthropic", "openai"})
+
+
+def unsupported_provider_error(hermes_args: tuple[str, ...] | list[str]) -> str | None:
+ """Return an error unless ``--provider`` names a provider Headroom can route.
+
+ ponytail: the flag is required on purpose. Hermes also resolves a provider
+ from config.yaml and HERMES_INFERENCE_PROVIDER; mirroring that order here
+ would drift. Parse them only if requiring the flag proves too strict.
+ """
+ args = list(hermes_args)
+ provider = ""
+ for index, arg in enumerate(args):
+ if arg == "--provider" and index + 1 < len(args):
+ provider = args[index + 1]
+ elif arg.startswith("--provider="):
+ provider = arg.split("=", 1)[1]
+ if provider.strip().lower() in _ROUTED_PROVIDERS:
+ return None
+ selected = f"'{provider}'" if provider else "no --provider flag"
+ return (
+ f"Error: Headroom cannot route this Hermes launch ({selected}).\n"
+ "Only the anthropic and openai providers go through Headroom. Hermes's "
+ "default provider (openrouter) and others such as nous call their own "
+ "endpoints.\n"
+ "Run: headroom wrap hermes -- --provider anthropic\n"
+ "To use another provider, run `hermes` directly, without Headroom."
+ )
+
+
def is_scoped_coding_agent_path(path: str) -> bool:
"""Return whether *path* is a Hermes scoped coding-agent endpoint."""
return (path.startswith("/api/codex-proxy/") and path.endswith(_CODEX_RESPONSES_SUFFIX)) or (
diff --git a/plugins/hermes/README.md b/plugins/hermes/README.md
index ee42376b2..55962614b 100644
--- a/plugins/hermes/README.md
+++ b/plugins/hermes/README.md
@@ -41,6 +41,16 @@ This plugin closes the loop by calling the proxy's `POST /v1/retrieve` HTTP endp
3. Restart the Hermes gateway / TUI (plugin discovery is cached per process).
+## Supported Hermes providers
+
+`headroom wrap hermes` sets `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL`. Hermes uses these only for the `anthropic` and `openai` providers. Its default provider (`openrouter`) and others such as `nous` call their own endpoints and skip Headroom. You must pick a routed provider with `--provider`, for example:
+
+```bash
+headroom wrap hermes -- --provider anthropic
+```
+
+The wrapper stops with an error before it starts the proxy or Hermes when `--provider` is missing or is not `anthropic` or `openai`. This includes a provider set only in `~/.hermes/config.yaml`. To use another provider, run `hermes` directly, without Headroom.
+
## Recommended proxy configuration
Hermes tool names don't match headroom's built-in `DEFAULT_EXCLUDE_TOOLS` (which protects Claude Code's `Read`/`Grep`/`Edit`/...), so two exclusions are strongly recommended on the proxy side:
diff --git a/tests/test_cli/test_wrap_hermes.py b/tests/test_cli/test_wrap_hermes.py
new file mode 100644
index 000000000..c276cfe4e
--- /dev/null
+++ b/tests/test_cli/test_wrap_hermes.py
@@ -0,0 +1,113 @@
+"""Tests for `headroom wrap hermes` command."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from click.testing import CliRunner
+
+from headroom.cli import wrap as wrap_mod
+from headroom.cli.main import main
+
+
+def runner() -> CliRunner:
+ return CliRunner()
+
+
+def test_wrap_hermes_sets_provider_envs(
+ runner: CliRunner,
+ tmp_path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """OPENAI_BASE_URL and ANTHROPIC_BASE_URL are set on launch."""
+ monkeypatch.chdir(tmp_path)
+ captured: dict[str, object] = {}
+
+ def fake_launch_tool(**kwargs): # noqa: ANN003
+ captured.update(kwargs)
+
+ with patch.object(wrap_mod.shutil, "which", return_value="hermes"):
+ with patch.object(wrap_mod, "_launch_tool", side_effect=fake_launch_tool):
+ result = runner.invoke(
+ main, ["wrap", "hermes", "--port", "9000", "--", "--provider", "anthropic"]
+ )
+
+ assert result.exit_code == 0, result.output
+ env = captured["env"]
+ assert isinstance(env, dict)
+ assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9000/v1"
+ assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9000"
+ assert captured["tool_label"] == "HERMES"
+ assert captured["agent_type"] == "hermes"
+ assert captured["args"] == ("--provider", "anthropic")
+
+
+def test_wrap_hermes_missing_binary_errors_clearly(
+ runner: CliRunner,
+ tmp_path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """If the hermes binary is missing, fail with a clear error."""
+ monkeypatch.chdir(tmp_path)
+ with patch.object(wrap_mod.shutil, "which", return_value=None):
+ result = runner.invoke(main, ["wrap", "hermes"])
+
+ assert result.exit_code == 1
+ assert result.output == (
+ "Error: 'hermes' not found in PATH.\n"
+ "Install Hermes: https://hermes-agent.nousresearch.com/\n"
+ )
+
+
+def test_wrap_hermes_prepare_only_exits_cleanly(
+ runner: CliRunner,
+ tmp_path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """--prepare-only must not attempt to launch Hermes."""
+ monkeypatch.chdir(tmp_path)
+ with patch.object(wrap_mod, "_launch_tool") as launch_tool:
+ result = runner.invoke(main, ["wrap", "hermes", "--prepare-only"])
+
+ assert result.exit_code == 0, result.output
+ launch_tool.assert_not_called()
+
+
+ "hermes_args",
+ [(), ("--provider", "openrouter"), ("--provider=nous",), ("--provider", "custom")],
+)
+def test_wrap_hermes_rejects_unrouted_provider_before_launch(
+ runner: CliRunner,
+ tmp_path,
+ monkeypatch: pytest.MonkeyPatch,
+ hermes_args: tuple[str, ...],
+) -> None:
+ monkeypatch.chdir(tmp_path)
+ with patch.object(wrap_mod.shutil, "which", return_value="hermes"):
+ with patch.object(wrap_mod, "_launch_tool") as launch:
+ result = runner.invoke(main, ["wrap", "hermes", "--", *hermes_args])
+
+ assert result.exit_code == 1
+ assert "cannot route" in result.output
+ assert "routed through Headroom" not in result.output
+ launch.assert_not_called()
+
+
[email protected]("provider", ["anthropic", "openai"])
+def test_wrap_hermes_launches_routed_provider(
+ runner: CliRunner,
+ tmp_path,
+ monkeypatch: pytest.MonkeyPatch,
+ provider: str,
+) -> None:
+ monkeypatch.chdir(tmp_path)
+ with patch.object(wrap_mod.shutil, "which", return_value="hermes"):
+ with patch.object(wrap_mod, "_launch_tool") as launch:
+ result = runner.invoke(main, ["wrap", "hermes", "--", "--provider", provider])
+
+ assert result.exit_code == 0, result.output
+ launch.assert_called_once()
+ assert launch.call_args.kwargs["args"] == ("--provider", provider)
diff --git a/tests/test_providers/test_hermes.py b/tests/test_providers/test_hermes.py
new file mode 100644
index 000000000..f386fdf0a
--- /dev/null
+++ b/tests/test_providers/test_hermes.py
@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from headroom.providers.hermes import build_launch_env
+
+
+def test_build_launch_env_sets_openai_base_url() -> None:
+ env, _ = build_launch_env(9000, {})
+
+ assert env["OPENAI_BASE_URL"] == "http://127.0.0.1:9000/v1"
+
+
+def test_build_launch_env_sets_anthropic_base_url() -> None:
+ env, _ = build_launch_env(9000, {})
+
+ assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:9000"
+
+
+def test_build_launch_env_returns_display_strings() -> None:
+ _, lines = build_launch_env(9000, {})
+
+ assert lines == [
+ "OPENAI_BASE_URL=http://127.0.0.1:9000/v1",
+ "ANTHROPIC_BASE_URL=http://127.0.0.1:9000",
+ ]
+
+
+def test_build_launch_env_inherits_base_environ() -> None:
+ env, _ = build_launch_env(9000, {"EXISTING_KEY": "existing-value"})
+
+ assert env["EXISTING_KEY"] == "existing-value"
+
+
+def test_build_launch_env_empty_mapping_does_not_inherit_host(monkeypatch) -> None:
+ monkeypatch.setenv("HEADROOM_TEST_HOST_ONLY", "1")
+ env, _ = build_launch_env(9000, {})
+ assert "HEADROOM_TEST_HOST_ONLY" not in env
+
+
+def test_provider_error_for_default_and_unsupported_providers() -> None:
+ from headroom.providers.hermes import unsupported_provider_error
+
+ assert unsupported_provider_error(()) is not None
+ assert unsupported_provider_error(("--provider",)) is not None
+ assert unsupported_provider_error(("--provider", "openrouter")) is not None
+ assert unsupported_provider_error(("--provider=nous",)) is not None
+ assert unsupported_provider_error(("--provider", "custom")) is not None
+
+
+def test_provider_error_silent_for_routed_providers() -> None:
+ from headroom.providers.hermes import unsupported_provider_error
+
+ assert unsupported_provider_error(("-z", "hi", "--provider", "anthropic")) is None
+ assert unsupported_provider_error(("--provider=OpenAI",)) is None
+ assert unsupported_provider_error(("--provider", "openrouter", "--provider", "openai")) is None