homelabstack/docs/superpowers/specs/2026-06-27-hermes-ecosystem-integration-design.md

Hermes Ecosystem Integration — Triage & Design

Date: 2026-06-27 Author: Claude (overnight autonomous research for ginnoir; for morning review) Status: Draft — awaiting ginnoir's decisions on the flagged items below

---

⚠️ REVISION 2026-06-27 (during execution — live-CLI findings supersede README research)

This spec was written from the repos' READMEs. Executing Phase 1 against the live valhalla host revealed Hermes v0.17 already ships native equivalents of several planned adds. Net changes:

• hermes-curator-evolver → DROPPED. Native hermes curator is already enabled, weekly, and conservative (consolidate: off, prune-only, never deletes, auto-backups), managing 74 agent-created skills. It satisfies the "report-only skill maintenance" intent. Installing the plugin would put a second curator on the same ~/.hermes/skills/. Use the native one (tune config line 417 if desired).
• camofox-browser → RE-EVALUATE. Native bundled plugins browser-browserbase (stealth/proxies/keep-alive, cloud) + browser-browser-use, plus hermes acp --setup-browser (local Playwright), already cover browsing. camofox now only wins the self-hosted-stealth-on- valhalla, no-cloud-key niche. Otherwise enable a native browser plugin (far less work).
• hermes-agent-acp-skill → KEPT & INSTALLED (enabled). Native hermes acp is an editor- integration server (Zed/VS Code/JetBrains), distinct from this delegation skill; they coexist.
• eagle-eye → KEPT / ELEVATED. 74 agent skills + 59 bundled makes per-turn skill routing more valuable (confirm native doesn't already pre-select).
• hermes-motif → OPTIONAL / lower priority. Still additive (native curator does lifecycle, not trace→new-skill discovery), but the library is already large and well-managed.
• hermes-web-search-plus → KEPT (no native web search observed). llmtrim overlaps native hermes insights for measurement; its trimming value stands.

As-built so far: acp-orchestrator skill installed + enabled. Cursor CLI installed; Claude Code + Codex installed (login pending). agy (Antigravity) install blocked by the sandbox classifier — see §7.4. The phase tables below are otherwise unchanged; treat the bullets above as the authoritative deltas.

---

0. TL;DR for the morning

You asked me to research seven Hermes-ecosystem repos and plan how each fits. I verified all seven are real and active, mapped each against your actual Hermes deployment (host systemd install on valhalla, llama-swap/P100 backend, ~29-tool curated MCP surface, Codex + Claude Code also installed), and triaged them into adopt / trial / decide / skip.

Recommended path:

Phase	Repo	Verdict	Why
1	hermes-agent-acp-skill	ADOPT	Pure skill drop-in; lets the local 20B offload hard work to Codex/Claude Code, which you already run. Highest leverage, lowest risk.
1	hermes-curator-evolver	ADOPT (dry-run first)	Closes Hermes' self-improvement loop; read-only by default; aligns with your curation habit.
2	camofox-browser	ADOPT (new homelab stack)	Gives the local agent real web browsing; clean Docker/Caddy fit; independent of Hermes internals.
2	eagle-eye	TRIAL / DEFER	Solves the exact tool-overload pain you already hit — but very early (5★, 1 commit) and carries a required Chinese-tokenizer dep. Trial behind a flag; don't depend on it.
3	hermes-ui	ADOPT (trial)	Single-HTML + stdlib proxy; stood up next to the bundled webui to evaluate.
3	hermes-workspace	ADOPT (trial)	Full command center; stood up in parallel to compare head-to-head, then keep one. Swarm Mode won't parallelize on one P100 — value is the workspace/observability features.
3	mission-control	SKIP	Not Hermes-native (built for OpenClaw/CrewAI/LangGraph/AutoGen). Redundant with the two Hermes UIs.

Decisions — RESOLVED 2026-06-27 (see Section 6): (1) trial both UIs, keep the winner; (2) curator-evolver stays report-only for now; (3) trial eagle-eye — it's the only direct skill-router in the ecosystem, no more-mature equivalent exists; (4) wire camofox as a minimal 2-tool skill.

---

1. The anchor: your current Hermes deployment

Everything below is sized against what you actually run (from project memory, verified against the repo and host conventions):

• Hermes Agent v0.17.0 (NousResearch) runs on the valhalla host, not in Docker — systemd units hermes-gateway.service, hermes-dashboard.service, hermes-webui.service. Editable install at ~/.hermes/hermes-agent/; config at ~/.hermes/config.yaml; CLI ~/.local/bin/hermes. Workspace at /storage1/hermes/workspace/.
• Backend: llama-swap (stacks/llm, Portainer id 34) on a single Tesla P100 16GB, serving one GGUF at a time, --parallel 1, 64k ctx, default gpt-oss-20b. OpenAI API at http://172.20.0.1:8090/v1.
• MCP surface deliberately curated to ~29 tools because gpt-oss-20b drowns in tool overload. This is the single most important constraint for everything below: the local model is weak at selection under load, and the GPU runs one model, one sequence at a time.
• You also run Codex (~/.codex) and Claude Code, kept in sync with your Claude global config. This is what makes the ACP delegation skill genuinely useful rather than theoretical.

1.1 Two integration classes (this drives the whole plan)

• Class A — host-side Hermes extensions (plugins & skills): live in ~/.hermes/ on valhalla, applied by SSH + hermes ... + gateway restart. These are NOT homelabstack repo content. They are host-managed exactly like the rustdesk/obsidian/xvfb units — tracked in project memory and the Obsidian vault, not committed here. Fully reversible (config backups + plugin uninstall). → hermes-agent-acp-skill, hermes-curator-evolver, eagle-eye.
• Class B — Docker services: become stacks/<name>/ entries, deployed via the normal Gitea-poll path, fronted by Caddy (internal_only + Authentik), secrets in stack.env, infra images pinned out of Watchtower. → camofox-browser, and (if adopted) hermes-ui / hermes-workspace / mission-control.

---

2. Per-repo analysis

2.1 hermes-agent-acp-skill (Rainhoole) — ADOPT, Phase 1

• What: A Hermes skill (SKILL.md + README.md, MIT) implementing delegate_task() — multi-agent delegation across Hermes internal subagents, Codex, and Claude Code. Handles agent routing (agent=...), context isolation, and safety controls (recommended 900 s external timeout, 24,000-char output cap).
• Fit: Strong and specific. Your local model is gpt-oss-20b — fine for orchestration and light tasks, weak for real implementation/review. This skill lets Hermes route the hard parts to the frontier CLIs you already have installed and configured. It turns the weak local brain into a dispatcher.
• Risk: Low. It's a skill file, not running code you didn't write — but it invokes external agents, so the real work is verifying Codex/Claude Code are launchable from the Hermes service environment (PATH, auth, non-interactive flags) and that timeouts/output caps are sane.
• Implementation sketch: Drop into ~/.hermes skills dir (or hermes skills install if the repo packages it that way — verify on the host); set delegation targets to the Codex + Claude Code invocations; restart gateway; smoke-test a trivial delegated task end-to-end.

2.2 hermes-curator-evolver (pingchesu) — ADOPT, dry-run first, Phase 1

• What: Local-first Hermes plugin (Python 3.11, SQLite, hermes plugins install). Mines evidence from sessions/tool-calls, ranks skill-improvement candidates, and generates dry-run, reviewable proposals. Read-only by default; mutations require explicit --approve. Only touches local agent-created skills — skips bundled, hub-installed, and external skills. Size guardrails, backup/rollback manifests, optional Qwen-embeddings + BGE-reranker for semantic ranking, native scheduler (systemd) integration.
• Fit: This is Hermes' "self-improving" thesis made operational, and it matches how you already work (curate, gate, keep things reversible). The default posture (report-only, dry-run, human-review queue) is exactly the safe on-ramp.
• Risk / caveats:
  • It writes to skills with --approve. Recommendation: run report-only / dry-run indefinitely at first; promote to --approve only after you've seen a few proposal batches you'd have accepted anyway.
  • Optional embeddings/reranker want a model. Do not load them onto the P100 alongside gpt-oss — the GPU is single-model/--parallel 1. Run ranking on CPU, or skip the dense layer initially (BM25/FTS ranking is enough to start).
  • Schedule the mining pass off-peak via a systemd timer so it never contends with live inference.
• Implementation sketch: hermes plugins install on the host; point it at the session store; run one manual collect→rank→report cycle by hand; inspect the review queue; only then wire a nightly systemd timer in report-only mode.

2.3 eagle-eye (willingning-coder) — TRIAL / DEFER, Phase 2

• What: Zero-invasive skill pre-filter plugin. Before the LLM call, narrows 50+ skills to the top ~5 via a 5-layer cascade (hard triggers → FTS5/BM25 → synonyms → dense embeddings → RRF fusion), degrading gracefully when optional deps are absent. "Not matching is a valid result."
• Fit (conceptual): Excellent — this is the skill-side analog of the MCP tool-overload fix you already did. Fewer, better skill candidates in the prompt = better selection by a weak model + less Pascal prefill. If it works, it directly improves gpt-oss-20b's behavior.
• Risk / caveats (why it's a trial, not an adopt):
  • Maturity: 5 stars, single commit. Early. Treat as experimental.
  • Dependency smell: jieba (Chinese tokenization) is a required dep; your skill library is English. Works, but signals the author's primary use case differs from yours — watch for English-tokenization edge cases and maintenance drift.
  • Same P100 rule: keep its dense-embedding layer on CPU or disabled; lean on L1–L2 (deterministic + BM25) first.
• Implementation sketch: Install behind an easy on/off switch on the host; A/B a handful of representative prompts with it on vs off; keep it only if measured skill-selection quality improves. Do not let any workflow depend on it.

2.4 camofox-browser (jo-inc) — ADOPT as a homelab stack, Phase 2

• What: Stealth headless browser (Camoufox/Firefox) exposing a REST API for AI agents — anti-fingerprinting, element-reference interaction (e1,e2), session isolation, proxy/GeoIP, YouTube transcripts, Docker/Fly/Railway deploy. 7.2k★, actively maintained. No Hermes coupling — it's a generic tool backend.
• Fit: Clean Class-B homelab fit and a real capability gap-filler: your agent currently has freshrss + obsidian but no general web browser. As stacks/camofox, internal-only behind Caddy, it gives Hermes (and Codex/Claude) reliable browsing.
• Risk / caveats:
  • It's anti-detection tooling — appropriate for personal research; keep it strictly LAN/SSO-gated (import internal_only + Authentik) and off the public internet. New attack surface; pin the image and read the Dockerfile before running.
  • Heavier service (~300 MB Camoufox binary, Firefox). Fine on valhalla, but it's not free.
  • Wiring to Hermes: either a thin MCP shim around its REST API, or a Hermes skill that curls it. Given your tool-overload sensitivity, expose it as one or two high-level tools (e.g. browse(url), search(query)), not its full surface.
• Implementation sketch: New stacks/camofox/docker-compose.yml (bind config to /config/camofox, blobs/cache to /storage1/labdata/camofox, join edge), stack.env, a Caddy block (camofox.ginnoir.com, import internal_only), regenerate bookmarks, push. Then add the minimal Hermes tool/skill wrapper on the host and restart the gateway.

2.5 The three dashboards — pick at most one (Phase 3, DECISION)

You already run the bundled hermes-webui.service, so a UI is an upgrade, not a gap. These three overlap heavily; adopting more than one is waste.

	hermes-ui (pyrate-llama)	hermes-workspace (outsourc-e)	mission-control (builderz-labs)
Stars	173	5.9k	5.4k
Stack	1 HTML file + Python stdlib proxy (serve_lite.py, :3333 → gateway :8642)	React/TS/Vite build, Node 22+, → gateway :8642 + dashboard :9119	Next.js 16 / React 19, better-sqlite3
Hermes-native?	Yes	Yes (best with vanilla hermes-agent)	No (OpenClaw/CrewAI/LangGraph/AutoGen/Claude SDK)
Effort to host	Trivial (no build)	Medium (build → container/stack)	Medium + adapter work
Headline features	chat, tasks/kanban, files, terminal, skills, MCP browser, cron, memory, health	all of the above + ops dashboards, "Conductor" missions, Swarm Mode (tmux worker pools)	32 panels, RBAC, spend/trust scoring, multi-framework
Verdict	Trial first	Consider as a proper stack later	Skip / defer

• hermes-ui — recommended first move. Lowest cost to evaluate a richer UI. Can run as a tiny host service or a minimal container next to the bundled webui; no build pipeline. If it's better than the bundled webui, keep it; if not, delete one file.
• hermes-workspace — the ambitious option. Genuinely the most capable, best run as a real stacks/hermes-workspace Docker build behind Caddy + Authentik. Caveat to flag: its marquee Swarm Mode (parallel tmux worker pools) cannot actually parallelize inference on your setup — the single P100 runs one model with --parallel 1, so "swarm" workers serialize on the GPU (or must use a different/remote backend per worker). Adopt for the workspace/observability features, not for swarm, unless/until you add GPU capacity or point swarm workers at cloud providers.
• mission-control — skip unless requirements change. It's framework-agnostic and not Hermes-native — using it means writing a Hermes adapter for a dashboard whose job the two Hermes-native UIs already do. Only worth it if you later want a single ops plane across multiple agent frameworks (you don't run those today).

---

3. Recommended phased rollout

Phase 1 — host-side, reversible, high-leverage (no repo changes):

1. hermes-agent-acp-skill — install skill, wire Codex + Claude Code delegation targets, smoke-test.
2. hermes-curator-evolver — install plugin in report-only/dry-run, manual cycle, then nightly systemd timer (report-only). CPU ranking; no P100 embeddings.

Phase 2 — new capability + experiment: 3. camofox-browser — new stacks/camofox (Class B), Caddy internal-only + Authentik, minimal Hermes tool wrapper. 4. eagle-eye — host-side trial behind an on/off switch; A/B skill-selection; keep only if it helps.

Phase 3 — UI decision (your call): 5. Trial hermes-ui alongside the bundled webui. Evaluate hermes-workspace as a stack if the workspace features justify the build. Skip mission-control.

Each phase is independently shippable and independently reversible. Stop after any phase.

---

4. Cross-cutting concerns (apply to every adoption)

• Single-P100 discipline. One GPU, one model, --parallel 1. Anything implying parallel or extra model loads — curator embeddings, eagle-eye dense layer, workspace swarm — must run on CPU, off-peak, or not at all. Never co-resident with gpt-oss on the P100.
• Host vs repo boundary. Class-A extensions are host-managed in ~/.hermes/ (document in memory
  • vault, like the rustdesk/obsidian units). Only Class-B services touch this repo. Don't accidentally commit host config here.
• Tool/skill surface minimalism. The whole reason your MCP is curated to ~29 tools. Expose new capabilities (camofox, delegation) as a few high-level tools, not raw surfaces, or you reintroduce the overload you fixed.
• Provenance & safety. Several repos are small/young (eagle-eye 1 commit; acp-skill 1 commit). Read the code before running it, especially anything that writes skills (curator) or executes shell / external agents (acp-skill, camofox). Pin to a reviewed commit/tag; keep stack images out of Watchtower auto-update.
• Reversibility. Back up ~/.hermes/config.yaml before each Class-A change (you already do this); snapshot before promoting curator to --approve.
• Security posture. Class-B services: import internal_only + Authentik, secrets in stack.env (LF endings), never public.

---

5. What I am explicitly NOT proposing

• Not running curator-evolver in --approve (auto-skill-editing) mode out of the gate.
• Not loading any second model onto the P100 (no GPU embeddings, no GPU swarm).
• Not adopting more than one dashboard.
• Not committing host-side Hermes plugins/skills into the homelabstack repo.
• Not exposing camofox or any new UI to the public internet.

---

6. DECISIONS — RESOLVED 2026-06-27

1. UI direction → trial BOTH. Stand up hermes-ui and hermes-workspace in parallel, evaluate head-to-head against the bundled webui, then keep the winner and remove the other. (Phase 3 now builds both.)
2. Curator autonomy → report-only for now. hermes-curator-evolver runs dry-run/report only; no --approve / --apply-low-risk / --approve-auto-apply. Revisit after a trust period.
3. eagle-eye → trial it. Rationale (ginnoir): wants a large skill library available without weighting every turn — which is exactly eagle-eye's pre-LLM skill-selection job. Research result: eagle-eye is the only direct skill-router in the Hermes ecosystem (per awesome-hermes-agent / Hermes Atlas); the nominal "alternatives" do different jobs — llmtrim (compresses tool schemas + MCP output; complementary, worth a later look for the tool side), rtk-hermes (shell-output compression), hermes-snow-search (faster session search), hermes-motif (mines traces into micro-skills; a curator-evolver rival, not a router). So eagle-eye stands, with the trial caveat (1-commit maturity, jieba dep): keep only if it measurably improves selection; run L1+L2 only (no P100 embeddings).
4. camofox wiring → minimal. A small 2-tool Hermes skill (browse, search) over the REST API, not the full surface or an MCP shim — protects the curated tool budget.

All four resolved ⇒ Phases 1, 2, and 3 are all actionable. The implementation plan that follows details every phase.

Ecosystem expansion (added 2026-06-27, per ginnoir): while researching eagle-eye alternatives I surveyed the wider Hermes ecosystem and the external-agent landscape. The worthwhile additions and the motif-vs-curator verdict are in §7. Claude Code + Codex are already installed on valhalla (this session); Cursor + Antigravity are scoped for the delegation fabric.

---

7. Ecosystem expansion & the delegation fabric (added 2026-06-27)

7.1 hermes-motif vs hermes-curator-evolver — verdict: complementary, run both

I earlier mis-framed these as rivals. They do different halves of one loop:

• hermes-motif (Saurav0989) — skill DISCOVERY. Watches tool calls live, finds repeated sequences (same tools, varying args → {variable}), and proposes them as new SKILL.md drafts. Makes no LLM calls — pure pattern-mining, so zero P100 cost. auto_install: false = proposal-only. Zero-to-one skill creation.
• hermes-curator-evolver (pingchesu) — skill REFINEMENT. Improves existing agent-created skills from session evidence; bounded, reviewable edits; report-only default; more mature (CI, systemd scheduler, backup/rollback).

Fit for you: your stated goal (eagle-eye rationale) is a large skill library without per-turn weight. That's a skill factory: motif manufactures new skills from what you already do repeatedly → curator refines them → eagle-eye routes among them at call time. They compose. Recommendation: run both in proposal/report-only mode. If you insist on only one to start, motif is the lower-risk, higher-immediate-value pick for growing a library (no model cost, no edits to existing files) — but there's no reason to drop curator; it's already Phase 1 and free to leave in report-only. Plan adds motif as Task 3b.

7.2 hermes-web-search-plus — ADOPT (pairs with camofox)

Mature (v2.6.1, MIT, stdlib-only) Hermes plugin: multi-provider web search + extraction with intent-aware routing (news/shopping/docs/GitHub/academic/security) and a research mode. 14 providers, all keys optional — works with a single configured provider (free tiers exist: Tavily, Exa, SearXNG self-host, Keenable keyless). Complements camofox, doesn't overlap it: search-plus finds (cheap API calls), camofox browses/interacts (heavy headless Firefox). For a P100-limited local agent, search-plus is the lighter, higher-frequency tool — arguably the one to reach for first; camofox for when a page needs real rendering/interaction. Plan adds it as Task 5b, before/with camofox. Install: hermes plugins install robbyczgw-cla/hermes-web-search-plus --enable.

7.3 Context-efficiency layer — OPTIONAL, helps the Pascal bottleneck

Your memory notes prefill is the P100 differentiator and context bloat is the enemy. Two opt-in tools:

• llmtrim (fkiene, MPL-2.0) — HTTPS-proxy / MCP / CLI that compresses **tool schemas + history
  • tool output** before requests (claims −31% input / −74% output tokens, BM25+ context ranking, log-templating). Works with anything honoring HTTPS_PROXY (Claude Code, Cursor, Aider). Two distinct payoffs: (a) in front of the cloud delegation agents (Claude Code/Codex/Cursor → Anthropic/OpenAI) it cuts real $ cost; (b) potentially in front of llama-swap (via LLMTRIM_EXTRA_HOSTS) to shrink prompts and speed Pascal prefill — needs validation, it's not documented for local OpenAI-compatible backends. Caveat: it installs a name-constrained MITM CA; acceptable but a real trust decision.
• rtk-hermes (ogallotti, MIT) — pre_tool_call hook that rewrites shell commands through the rtk binary so terminal output arrives pre-filtered (cache-safe; preserves tool schema). Lighter, shell-only. Needs the rtk binary on the host (brew/Linux build — verify availability).

Recommendation: defer both to an opt-in Task 11. Start llmtrim on the cloud-delegation path (clear cost win, no local risk) before considering it in front of llama-swap.

7.4 The delegation fabric — claude-code · codex · cursor · antigravity

Your acp-skill (Task 2) natively routes to codex, claude-code, and hermes subagents. You also want Cursor and Antigravity in the mix. All four have real headless CLIs usable as delegation targets from the valhalla host:

Agent	CLI	Headless invocation	Install (official)	Status on valhalla
Claude Code	claude	claude -p	curl -fsSL https://claude.ai/install.sh | bash → ~/.local/bin/claude	Installed v2.1.195 (login pending)
Codex	codex	codex exec / non-interactive	npm i -g @openai/codex (Node 22+)	Installed v0.142.3 (login pending)
Cursor	cursor-agent	cursor-agent -p --output-format json --trust	curl https://cursor.com/install -fsS | bash	Scoped (Task 10) — note: known -p hang bug, set --output-format json + timeout
Antigravity	agy (ex-Gemini CLI, Go binary, best for headless SSH)	agy -p / --headless --approve	from official antigravity.google/download + /docs/gcli-migration (auth via keyring/Google sign-in or ANTIGRAVITY_TOKEN)	Scoped (Task 10)

Wiring approach (Task 10): acp-skill supports codex/claude-code/hermes out of the box — verify whether its agent= routing is extensible (read SKILL.md). If yes, add cursor and antigravity targets pointing at the headless invocations above. If not, add a thin generic "shell-agent" skill that shells out to any of the four with the timeout/output caps from the delegation: config — keeping the exposed tool surface minimal (your standing tool-budget rule). Alternatives noted, not adopted: 42-evey/hermes-plugins ships evey-bridge (file inbox/outbox

• MCP bridge to Claude Code) and evey-delegate-model (model routing w/ fallback) — heavier, opinionated, unknown maturity; acp-skill is the simpler purpose-built choice. evey-cost-guard (Langfuse budget enforcement) becomes worth a look once cloud delegation is live and spend matters.

7.5 Updated rollout placement

• Phase 1: + Task 3b hermes-motif (proposal-only, zero P100 cost).
• Phase 2: + Task 5b hermes-web-search-plus (light search, pairs with camofox).
• Phase 2b (new): Task 10 delegation fabric (install cursor + agy, wire all four into acp-skill) and Task 11 (optional) context efficiency (llmtrim on the cloud-delegation path; rtk for shell).
• Phase 3: unchanged (both UIs → keep one).