Skip to content

Commit 8d7cd9c

Browse files
authored
Merge pull request #164 from wonecosystem/feat/hermes-backend
feat(engineer): a hermes backend that runs the local hermes CLI
2 parents 0321574 + 2fedb3a commit 8d7cd9c

15 files changed

Lines changed: 940 additions & 11 deletions

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
- **`hermes` backend**: `"sdk": "hermes"` engineers a saved capture through the local [`hermes` CLI](https://hermes-agent.nousresearch.com/docs) (`hermes chat --oneshot --format stream-json`), so a run needs no API key in rae — the model, the provider and the authentication are the user's own Hermes configuration. `hermes chat` reads the prompt on stdin, so nothing the model reads is shell-parsed; `hermes_max_turns` overrides the turn cap from the user's Hermes config; runs start with `--ignore-rules` so an `AGENTS.md`/`CLAUDE.md` cannot steer them, and estimate cost from the CLI's token counts, leaving it at 0 for a model with no known price. The backend covers `engineer` only: with `"sdk": "hermes"` the `agent` command stops before browser setup, so capture with another SDK (claude, opencode, copilot or cursor) and engineer that run with hermes; `agent --dry-run` reports the same error. The CLI is found on `PATH` or through `RAE_HERMES_BIN`, and `agent --dry-run` reports it as a check.
12+
1013
## [0.15.0] - 2026-11-08
1114

1215
### Changed

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,9 @@ Settings live in `~/.reverse-api/config.json` and can be edited via `/settings`
108108
"opencode_auto_start": true,
109109
"opencode_base_url": "http://127.0.0.1:4096",
110110
"opencode_model": "big-pickle",
111+
"hermes_max_turns": null,
112+
"hermes_model": null,
113+
"hermes_provider": null,
111114
"opencode_npx_package": "opencode-ai@latest",
112115
"opencode_provider": "opencode",
113116
"copilot_model": "gpt-5",
@@ -120,7 +123,8 @@ Settings live in `~/.reverse-api/config.json` and can be edited via `/settings`
120123
```
121124

122125
- **Models**: Sonnet 5.5, Opus 5.5 (most capable), Opus 4.6 and Haiku 5.5 (fastest). Sonnet 4.6 stays the default until you choose another; it and Haiku 4.5 are still accepted in config and by `--model`. For OpenCode see [models.dev](https://models.dev).
123-
- **SDK**: `claude` (default), `opencode`, `cursor`, or `copilot` (GitHub Copilot).
126+
- **SDK**: `claude` (default), `opencode`, `cursor`, `copilot` (GitHub Copilot), or `hermes`.
127+
- **Hermes**: engineers a saved capture through the [`hermes` CLI](https://hermes-agent.nousresearch.com/docs) instead of an SDK. It needs Hermes Agent v2026.9.21 or later from the official installer (the PyPI package is older): `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash` on macOS, Linux and WSL2, `iex (irm https://hermes-agent.nousresearch.com/install.ps1)` in PowerShell on Windows. It needs no API key in rae: the model, the provider and the authentication are your own Hermes configuration. `hermes_model` and `hermes_provider` override which model that configuration runs; leaving them `null` uses whatever Hermes already selects. `hermes_max_turns` overrides the turn cap from your Hermes config. Runs start with `--ignore-rules`, so an `AGENTS.md` or `CLAUDE.md` in the workspace cannot steer the run. Cost is estimated from the token counts the CLI reports, and stays at 0 for a model with no known price. It covers `engineer` only: while `sdk` is `hermes` the `agent` command stops before opening a browser, so capture with `claude`, `opencode`, `copilot` or `cursor`, then switch `sdk` back to `hermes` to engineer that run. `agent --dry-run` reports the same thing.
124128
- **Claude settings isolation**: Claude sessions don't load your Claude Code settings files, `CLAUDE.md`, hooks, plugins, permission rules or MCP servers, so your personal setup doesn't steer the agent. Organization-managed policy still applies, and Claude Code still reads its own state such as `~/.claude.json` and auto memory. If `~/.claude/settings.json` provides your authentication (`apiKeyHelper`, or Bedrock, Vertex or proxy variables under `env`), set `claude_setting_sources` to the layers to load, e.g. `["user"]` or `["user", "project", "local"]`. Each layer you list is loaded in full, including its hooks, plugins, permission rules and MCP servers.
125129
- **OpenCode setup**: with `sdk: "opencode"`, RAE reuses an existing server or downloads/starts `opencode-ai@latest` through `npx`; a global OpenCode installation is not required. Fresh configurations default to the free `opencode/big-pickle` model. `/settings` shows a loading list, then offers a searchable **opencode provider / model** list populated from the server's connected, tool-capable catalog and marks free OpenCode options. Before creating a session, RAE validates the saved pair again and suggests currently available free models when configuration is invalid. Compatible older servers are reused with a version warning. Node.js 20+ is required for automatic startup. Password-protected servers use `OPENCODE_SERVER_PASSWORD` and optional `OPENCODE_SERVER_USERNAME`. Override startup with `OPENCODE_BASE_URL`, `RAE_OPENCODE_PACKAGE`, or `RAE_OPENCODE_AUTO_START=0`.
126130
- **Ollama through OpenCode**: choose provider `ollama` in `/settings`; RAE starts an installed Ollama daemon if needed, lists only installed models with tool calling and 64k+ context, and supplies OpenCode's provider config inline. Models are never downloaded silently. Override with `RAE_OLLAMA_BASE_URL` or `RAE_OLLAMA_AUTO_START=0`.

‎src/reverse_api/cli.py‎

Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ def default_model_for_configured_sdk(sdk: str | None = None) -> str:
7777
return str(config_manager.get("copilot_model") or "gpt-5")
7878
if s == "cursor":
7979
return str(config_manager.get("cursor_model") or "composer-2.5")
80+
if s == "hermes":
81+
return str(config_manager.get("hermes_model") or "hermes default")
8082
return str(config_manager.get("claude_code_model") or "claude-sonnet-4-6")
8183

8284

@@ -326,19 +328,33 @@ def _build_dry_run_payload(
326328
"message": f"unknown agent_provider {agent_provider!r}; expected 'auto', 'chrome-mcp', or 'agent-browser'",
327329
})
328330

329-
# 4. SDK + API key presence (we only check env var existence, not validity)
331+
# 4. SDK + API key presence (we only check env var existence, not validity).
332+
# Hermes authenticates through its own config, so the check there is its CLI, not a key.
330333
sdk = config_manager.get("sdk", "claude")
331334
sdk_env_var = {
332335
"claude": "ANTHROPIC_API_KEY",
333336
"opencode": "OPENCODE_API_KEY",
334337
"copilot": "GITHUB_COPILOT_TOKEN",
335338
"cursor": "CURSOR_API_KEY",
336339
}.get(sdk)
337-
if sdk_env_var is None:
340+
if sdk == "hermes":
341+
from .hermes_engineer import HERMES_BIN_ENV, hermes_binary, install_command
342+
343+
message = (
344+
"the hermes backend engineers a saved capture; it does not drive the browser, "
345+
"so agent capture needs another sdk — installing it does not change that"
346+
)
347+
if hermes_binary() is None:
348+
message = (
349+
"the hermes backend engineers a saved capture and it does not drive the browser; "
350+
f"agent capture needs another sdk. For engineer runs, install Hermes Agent with `{install_command()}` or set {HERMES_BIN_ENV}."
351+
)
352+
checks.append({"name": "sdk:hermes", "status": "error", "message": message})
353+
elif sdk_env_var is None:
338354
checks.append({
339355
"name": "sdk",
340356
"status": "error",
341-
"message": f"unknown sdk {sdk!r}; expected 'claude', 'opencode', 'copilot', or 'cursor'",
357+
"message": f"unknown sdk {sdk!r}; expected 'claude', 'opencode', 'copilot', 'cursor', or 'hermes'",
342358
})
343359
elif not os.environ.get(sdk_env_var):
344360
checks.append({
@@ -463,14 +479,16 @@ def _build_dry_run_payload(
463479
"opencode": "opencode_model",
464480
"copilot": "copilot_model",
465481
"cursor": "cursor_model",
482+
"hermes": "hermes_model",
466483
}.get(sdk, "claude_code_model")
467484
sdk_default_model = {
468485
"claude": "claude-sonnet-4-6",
469486
"opencode": "claude-opus-4-6",
470487
"copilot": "gpt-5",
471488
"cursor": "composer-2.5",
489+
"hermes": "hermes default",
472490
}.get(sdk, "claude-sonnet-4-6")
473-
resolved_model = model or config_manager.get(sdk_model_key, sdk_default_model)
491+
resolved_model = model or config_manager.get(sdk_model_key) or sdk_default_model
474492

475493
return {
476494
"schema_version": AGENT_JSON_SCHEMA_VERSION,
@@ -1144,6 +1162,14 @@ def run_auto_capture(
11441162
if not prompt:
11451163
raise click.UsageError("a prompt is required")
11461164

1165+
if (_session_sdk(resume) or config_manager.get("sdk", "claude")) == "hermes":
1166+
# Say it before any browser setup: this backend never drives one. A resumed run keeps
1167+
# the sdk it was captured with, so switching to hermes in /settings must not block it.
1168+
raise click.ClickException(
1169+
"the hermes backend engineers a saved capture; it does not drive the browser yet. "
1170+
"Capture with another sdk (claude, opencode, copilot or cursor), then engineer that run with sdk set to hermes."
1171+
)
1172+
11471173
if url:
11481174
url = normalize_url(url)
11491175

@@ -1633,6 +1659,7 @@ def run_engineer(
16331659
"opencode": resume_model or config_manager.get("opencode_model", DEFAULT_OPENCODE_MODEL),
16341660
"copilot": resume_model or config_manager.get("copilot_model", "gpt-5"),
16351661
"cursor": model or config_manager.get("cursor_model", "composer-2.5"),
1662+
"hermes": resume_model or config_manager.get("hermes_model") or "hermes default",
16361663
}.get(sdk) or model or config_manager.get("claude_code_model", "claude-sonnet-4-6")
16371664
on_session = _session_recorder(run_id, "engineer", sdk, session_model, output_dir, output_mode)
16381665

@@ -1677,6 +1704,28 @@ def run_engineer(
16771704
cost_before=cost_before,
16781705
on_session=on_session,
16791706
)
1707+
elif sdk == "hermes":
1708+
result = run_reverse_engineering(
1709+
run_id=run_id,
1710+
har_path=har_path,
1711+
prompt=prompt,
1712+
model=model,
1713+
output_dir=output_dir,
1714+
sdk=sdk,
1715+
hermes_model=None if session_model == "hermes default" else session_model,
1716+
hermes_provider=config_manager.get("hermes_provider"),
1717+
hermes_max_turns=config_manager.get("hermes_max_turns"),
1718+
enable_sync=enable_sync,
1719+
additional_instructions=additional_instructions,
1720+
is_fresh=is_fresh,
1721+
output_language=output_language,
1722+
output_mode=output_mode,
1723+
interactive=interactive,
1724+
json_event_sink=json_event_sink,
1725+
resume_session=resume_session,
1726+
cost_before=cost_before,
1727+
on_session=on_session,
1728+
)
16801729
elif sdk == "cursor":
16811730
_cs = config_manager.get("cursor_setting_sources")
16821731
_cursor_src = _cs if isinstance(_cs, list) and all(isinstance(x, str) for x in _cs) else None

‎src/reverse_api/config.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@
3030
# Optional override: list of setting source ids, e.g. ["project","user","all"]. None uses cursor_web_search.
3131
"cursor_setting_sources": None,
3232
"copilot_model": "gpt-5", # Model for Copilot SDK sessions
33+
"hermes_model": None, # None keeps whatever model the user's own Hermes config selects
34+
"hermes_provider": None, # None keeps the provider the user's own Hermes config selects
35+
"hermes_max_turns": None, # None keeps the cap from the user's own Hermes config
3336
"opencode_model": DEFAULT_OPENCODE_MODEL,
3437
"opencode_provider": DEFAULT_OPENCODE_PROVIDER,
3538
"opencode_auto_start": True,
@@ -40,7 +43,7 @@
4043
"output_dir": None, # None means use ~/.reverse-api/runs
4144
"output_language": "python", # "python", "javascript", "typescript", "go", "java", "csharp", "php", "ruby", "c", or "powershell"
4245
"real_time_sync": True, # Enable real-time file sync during engineering
43-
"sdk": "claude", # "claude", "opencode", "copilot", or "cursor"
46+
"sdk": "claude", # "claude", "opencode", "copilot", "cursor", or "hermes"
4447
}
4548

4649

‎src/reverse_api/engineer.py‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -434,6 +434,9 @@ def run_reverse_engineering(
434434
cursor_model: str | None = None,
435435
cursor_web_search: bool = True,
436436
cursor_setting_sources: list[str] | None = None,
437+
hermes_model: str | None = None,
438+
hermes_provider: str | None = None,
439+
hermes_max_turns: int | None = None,
437440
enable_sync: bool = False,
438441
is_fresh: bool = False,
439442
output_language: str = "python",
@@ -449,13 +452,16 @@ def run_reverse_engineering(
449452
resume_session, cost_before and on_session reopen and record the SDK session, see BaseEngineer.
450453
451454
Args:
452-
sdk: "claude", "opencode", "copilot", or "cursor" - determines which SDK to use
455+
sdk: "claude", "opencode", "copilot", "cursor", or "hermes" - determines which backend to use
453456
opencode_provider: Provider ID for OpenCode (e.g., "anthropic")
454457
opencode_model: Model ID for OpenCode (e.g., "claude-sonnet-4-6")
455458
copilot_model: Model ID for Copilot (e.g., "gpt-5")
456459
cursor_model: Model id for Cursor SDK (e.g., "composer-2.5")
457460
cursor_web_search: When True, load extra Cursor setting layers so WebFetch/WebSearch and plugins apply.
458461
cursor_setting_sources: Optional explicit list (overrides cursor_web_search), e.g. ["project","user","all"].
462+
hermes_model: Model for the Hermes CLI; None keeps the model its own config selects.
463+
hermes_provider: Provider for the Hermes CLI; None keeps the provider its own config selects.
464+
hermes_max_turns: Turn cap for a Hermes run; None keeps the cap its own config sets.
459465
enable_sync: Enable real-time file syncing during engineering
460466
is_fresh: Whether to start fresh (ignore previous scripts)
461467
output_language: Target language - "python", "javascript", "typescript", "go", "java", "csharp", "php", "ruby", or "c"
@@ -522,6 +528,27 @@ def run_reverse_engineering(
522528
copilot_model=copilot_model,
523529
interactive=interactive,
524530
)
531+
elif sdk == "hermes":
532+
from .hermes_engineer import HermesEngineer
533+
534+
engineer = HermesEngineer(
535+
run_id=run_id,
536+
har_path=har_path,
537+
prompt=prompt,
538+
model=model,
539+
additional_instructions=additional_instructions,
540+
output_dir=output_dir,
541+
verbose=verbose,
542+
enable_sync=enable_sync,
543+
sdk=sdk,
544+
is_fresh=is_fresh,
545+
output_language=output_language,
546+
output_mode=output_mode,
547+
hermes_model=hermes_model,
548+
hermes_provider=hermes_provider,
549+
hermes_max_turns=hermes_max_turns,
550+
interactive=interactive,
551+
)
525552
else:
526553
engineer = ClaudeEngineer(
527554
run_id=run_id,

0 commit comments

Comments
 (0)