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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(providers): add Hermes agent wrap support (#934)
Ashish Patel7877241d84c9
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex 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 instructionsheadroom wrap grok-build # Start proxy + configure Grok Buildheadroom wrap openclaw # Install + configure OpenClaw plugin+ headroom wrap hermes # Start proxy + Hermes agentheadroom wrap claude --port 9999 # Custom proxy portheadroom 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_errorfrom headroom.providers.kimi import build_launch_env as _build_kimi_launch_envfrom headroom.providers.mistral_vibe import build_launch_env as _build_mistral_vibe_launch_envfrom 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.pyindex 2538dfdcf..edf2e2574 100644--- a/headroom/providers/hermes.py+++ b/headroom/providers/hermes.py@@ -9,8 +9,13 @@ from __future__ import annotationsimport jsonimport logging+import os+from collections.abc import Mappingfrom 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.mdindex 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 endp3. 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 configurationHermes 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.pynew file mode 100644index 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.pynew file mode 100644index 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