ginnoir/homelabstack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fold ecosystem expansion + delegation fabric into Hermes plan

Browse Source 
Add hermes-motif (skill discovery; complementary to curator, not a rival),
hermes-web-search-plus (mature multi-provider search, pairs with camofox),
optional llmtrim/rtk context efficiency, and the claude/codex/cursor/antigravity
delegation fabric. Record that Claude Code + Codex are now installed on valhalla.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
ginnoir
2026-06-27 05:45:34 -05:00
co-authored by Claude Opus 4.8
parent 3cd843072d
commit dc2225d384
2 changed files with 299 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-06-27-hermes-ecosystem-integration.md
+207 -10
View File
@@ -55,13 +55,20 @@ ssh -o BatchMode=yes ginnoir@valhalla "cp ~/.hermes/config.yaml ~/.hermes/config
``` ```
Expected: a backup is created; directory listings print (note whether `~/.hermes/plugins` exists yet); `hermes` prints a version (≈ v0.17.0). Record the skills-dir path — confirms `~/.hermes/skills` is correct for later tasks. Expected: a backup is created; directory listings print (note whether `~/.hermes/plugins` exists yet); `hermes` prints a version (≈ v0.17.0). Record the skills-dir path — confirms `~/.hermes/skills` is correct for later tasks.
- [ ] **Step 3: Confirm Codex and Claude Code are invocable from the host as ginnoir** - [x] **Step 3: Confirm Codex and Claude Code are invocable — DONE 2026-06-27 (installed this session)**
Run: Both delegation CLIs were installed on valhalla this session:
- `claude` → `~/.local/bin/claude` **v2.1.195** (login pending)
- `codex` → `/usr/bin/codex` **v0.142.3** (login pending; harmless PATH-alias warning at install)
**Gotcha recorded:** `/home/ginnoir/.claude` existed as an empty **root-owned** dir (created Jun 17,
likely a prior sudo op) and blocked the installer until `sudo chown ginnoir:ginnoir ~/.claude`. Codex
global install needs `sudo` (npm global prefix is `/usr`). Re-verify any time with:
```bash ```bash
ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'which codex; which claude; codex --version 2>&1 | head -1; claude --version 2>&1 | head -1'" ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'claude --version; codex --version'"
``` ```
Expected: paths for both `codex` and `claude`, and a version line each. (Uses `-lc` to get the login PATH.) **If either is missing**, the ACP delegation skill (Task 2) can still install but its `codex`/`claude-code` targets will be non-functional until they're on the service PATH — note this for ginnoir. **ginnoir must log in** to each (`claude`, then `codex login`) before Task 2's external delegation
smoke-tests will succeed. Cursor + Antigravity targets are added later in **Task 10**.
- [ ] **Step 4: Checkpoint** - [ ] **Step 4: Checkpoint**
@@ -184,6 +191,52 @@ No git commit. Record: plugin at `~/.hermes/plugins/curator-evolver`, DB at `...
--- ---
## Task 3b: Install `hermes-motif` (skill DISCOVERY, proposal-only)
> Complements curator-evolver — does **not** compete with it (spec §7.1). motif *discovers new*
> skills by mining repeated tool sequences; curator *refines existing* ones. **Zero P100 cost**
> (makes no LLM calls). Together with eagle-eye (routing) they form a skill factory:
> motif creates → curator refines → eagle-eye routes.
**Files:**
- Host: `~/.hermes/plugins/` (motif plugin), `~/.hermes/plugins/<motif>/plugin/plugin.yaml`.
- [ ] **Step 1: Clone and read; confirm proposal-only config**
Run:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "git -C /storage1/hermes/workspace/clones clone https://github.com/Saurav0989/hermes-motif && sed -n '1,160p' /storage1/hermes/workspace/clones/hermes-motif/README.md && cat /storage1/hermes/workspace/clones/hermes-motif/plugin/plugin.yaml 2>&1"
```
Expected: README + `plugin.yaml` print. **Confirm `auto_install: false`** (proposal-only) and note
`min_occurrences` / sequence-length thresholds. Note the referenced Hermes trace bug (#12922) that
can affect trace completeness — acceptable for a proposal-only trial.
- [ ] **Step 2: Install the plugin**
Run (per its README — clone + pip + `scripts/install_plugin.sh`):
```bash
ssh -o BatchMode=yes ginnoir@valhalla "cd /storage1/hermes/workspace/clones/hermes-motif && bash scripts/install_plugin.sh 2>&1 | tail -20"
```
Expected: the plugin lands under `~/.hermes/plugins/` and registers. (If the script expects a
different layout, follow the README's exact steps.)
- [ ] **Step 3: Verify it mines and PROPOSES without modifying skills**
Restart the gateway, run the agent through a couple of repeated multi-tool workflows, then check for
proposals (drafts), confirming nothing under `~/.hermes/skills` was auto-written:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "sudo systemctl restart hermes-gateway.service && sleep 5 && find ~/.hermes/plugins -iname '*propos*' -o -iname '*draft*' 2>/dev/null | head && find ~/.hermes/skills -newermt '-10 minutes' -type f 2>/dev/null"
```
Expected: proposal/draft artifacts may appear under the plugin dir; the second `find` is **empty**
(no skill files auto-modified) — proves `auto_install: false` safety.
- [ ] **Step 4: Checkpoint**
No repo commit (host-side). **Rollback** = remove the motif plugin dir + restart gateway. Record in
`memory/hermes-extensions.md` alongside curator (skill factory: motif=create, curator=refine).
---
## Task 4: Document Phase 1 in memory + vault (durable knowledge) ## Task 4: Document Phase 1 in memory + vault (durable knowledge)
**Files:** **Files:**
@@ -192,7 +245,7 @@ No git commit. Record: plugin at `~/.hermes/plugins/curator-evolver`, DB at `...
- [ ] **Step 1: Write the memory file** - [ ] **Step 1: Write the memory file**
Create `memory/hermes-extensions.md` (frontmatter `type: project`) recording: acp-skill installed (delegation to hermes/codex/claude-code, 900s/24k caps), curator-evolver installed **report-only** (CPU ranking, no `--semantic`, no auto-apply flags), exact paths and rollback commands, and the host-vs-repo boundary. Link `[[llm-stack-hermes]]`, `[[multi-agent-tool-configs]]`, `[[obsidian-app-on-valhalla]]`. Create `memory/hermes-extensions.md` (frontmatter `type: project`) recording: acp-skill installed (delegation to hermes/codex/claude-code/cursor/antigravity, 900s/24k caps); curator-evolver installed **report-only** (CPU ranking, no `--semantic`, no auto-apply flags); **motif** installed proposal-only (skill factory: motif creates → curator refines → eagle-eye routes); **claude v2.1.195 + codex v0.142.3 installed on valhalla 2026-06-27** (login pending; `~/.claude` was root-owned → chowned); exact paths and rollback commands; the host-vs-repo boundary. Link `[[llm-stack-hermes]]`, `[[multi-agent-tool-configs]]`, `[[obsidian-app-on-valhalla]]`.
- [ ] **Step 2: Add the MEMORY.md index pointer** - [ ] **Step 2: Add the MEMORY.md index pointer**
@@ -333,6 +386,47 @@ Repo changes are committed (Step 5). Update `memory/hermes-extensions.md` + the
--- ---
## Task 5b: Install `hermes-web-search-plus` (multi-provider search; pairs with camofox)
> Mature (v2.6.1, MIT, stdlib-only). Complements camofox (spec §7.2): search-plus *finds* via cheap
> provider APIs, camofox *browses/renders*. Lighter and higher-frequency — good default reach-for.
**Files:**
- Host: `~/.hermes/plugins/` (plugin), provider key(s) in `~/.hermes/config.yaml` (or the plugin's config).
- [ ] **Step 1: Install the plugin**
Run:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "bash -lc '~/.local/bin/hermes plugins install robbyczgw-cla/hermes-web-search-plus --enable'"
```
Expected: plugin installs and enables.
- [ ] **Step 2: Configure at least one provider key (free tier)**
All provider keys are optional but ≥1 is needed to function. Pick a free-tier provider (e.g. Tavily,
Exa, or self-hosted SearXNG; Keenable has a keyless public tier). Add the key per the plugin's README
(read `/storage1/hermes/workspace/clones/...` or the plugin docs for the exact env/config key), then:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "sudo systemctl restart hermes-gateway.service && sleep 5 && systemctl is-active hermes-gateway.service"
```
Expected: gateway `active`. **Mind the tool-budget rule** — if it exposes both `web_search_plus` +
extract, that's fine (2 tools); don't also enable redundant search MCPs.
- [ ] **Step 3: Smoke-test a search**
Run:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "~/.local/bin/hermes run 'search the web for the latest Hermes Agent release version and cite the source' 2>&1 | tail -20"
```
Expected: the agent calls the search tool, returns a current result with a source URL.
- [ ] **Step 4: Checkpoint**
No repo commit (host-side). Document the chosen provider + key location in `memory/hermes-extensions.md`.
---
## Task 6: Trial `eagle-eye` skill pre-filter (Class A, behind a switch) ## Task 6: Trial `eagle-eye` skill pre-filter (Class A, behind a switch)
> Confirmed the chosen tool: eagle-eye is the **only** direct skill-router in the Hermes ecosystem > Confirmed the chosen tool: eagle-eye is the **only** direct skill-router in the Hermes ecosystem
@@ -382,6 +476,106 @@ No repo commit (host-side). Document the A/B result and final state (kept/cut) i
--- ---
# PHASE 2b — Delegation fabric & context efficiency
> Extends acp-skill (Task 2) from 3 targets to 4 external agents, and adds optional token-trimming.
## Task 10: Wire Cursor + Antigravity into the delegation fabric
**Files:**
- Host: Cursor + `agy` binaries; acp-skill config or a generic shell-agent skill in `~/.hermes/skills/`.
- [ ] **Step 1: Install the Cursor CLI (official cursor.com)**
Run:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'curl https://cursor.com/install -fsS | bash' && ssh -o BatchMode=yes ginnoir@valhalla 'bash -lc \"command -v cursor-agent && cursor-agent --version\"'"
```
Expected: `cursor-agent` installs and prints a version. ginnoir logs in later.
- [ ] **Step 2: Install the Antigravity CLI (`agy`) from the OFFICIAL Google source**
Do **not** use blog-derived URLs. Get the exact installer from the official pages first:
`https://antigravity.google/download` and `https://antigravity.google/docs/gcli-migration`. Then run
the official one-line installer they document, e.g.:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "bash -lc '<official agy installer from antigravity.google/docs>' && ssh -o BatchMode=yes ginnoir@valhalla 'bash -lc \"command -v agy && agy --version\"'"
```
Expected: `agy` (Go binary, ideal for headless SSH) installs and prints a version. Auth later via
keyring/Google sign-in or `ANTIGRAVITY_TOKEN`.
- [ ] **Step 3: Confirm each agent answers in headless mode (after ginnoir logs in)**
Run:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'claude -p \"say PONG\"; codex exec \"say PONG\"; cursor-agent -p --output-format json --trust \"say PONG\"; agy -p \"say PONG\"'"
```
Expected: each prints PONG-ish output. **Cursor caveat:** `-p` has a known hang bug — always pass
`--output-format json` and wrap with a timeout (`timeout 120 cursor-agent ...`).
- [ ] **Step 4: Extend acp-skill routing (or add a generic shell-agent skill)**
Read `~/.hermes/skills/hermes-acp-orchestrator/SKILL.md` to see if `agent=` routing is extensible.
- **If extensible:** add `cursor` and `antigravity` targets mapping to the Step 3 invocations
(with the cursor timeout + json flags), honoring the `delegation:` `external_timeout_seconds: 900`
/ `external_max_output_chars: 24000` caps.
- **If not:** add `~/.hermes/skills/shell-agent/SKILL.md` exposing **one** tool
`delegate(agent, goal)` that shells out to claude/codex/cursor/agy with the caps + cursor guard.
One tool keeps the surface within the tool-budget.
Then restart the gateway:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "sudo systemctl restart hermes-gateway.service && sleep 5 && systemctl is-active hermes-gateway.service"
```
- [ ] **Step 5: End-to-end smoke-test each delegation target**
Run one delegated task per agent (e.g. `agent=cursor`, `agent=antigravity`) and confirm output is
captured under the cap. Record any that hang/auth-fail for follow-up.
- [ ] **Step 6: Checkpoint**
No repo commit (host-side). Document the four-target fabric + cursor caveat in `memory/hermes-extensions.md`.
---
## Task 11: (OPTIONAL) Context efficiency — llmtrim on the cloud-delegation path
> Opt-in. Start where the win is unambiguous and local-risk-free: trimming the **cloud** delegation
> agents' traffic (Claude Code/Codex/Cursor → Anthropic/OpenAI). Defer the llama-swap-fronting idea
> until validated. `rtk-hermes` (shell-output trimming) is a separate lighter opt-in.
**Files:**
- Host: llmtrim service + `HTTPS_PROXY` env for the delegation agents.
- [ ] **Step 1: Install llmtrim and run setup**
Run:
```bash
ssh -o BatchMode=yes ginnoir@valhalla "bash -lc 'npm install -g @llmtrim/cli@latest && llmtrim setup' 2>&1 | tail -20"
```
Expected: installs; `setup` installs the name-constrained CA + background proxy. **Review the MITM-CA
trust implication first** — it's name-constrained to LLM API domains, but it's still a CA on the host.
- [ ] **Step 2: Point the cloud delegation agents through it; measure**
Ensure the delegation agents inherit `HTTPS_PROXY` (llmtrim sets this). Run a representative delegated
task via Claude Code/Codex and compare token counts / cost before vs after (llmtrim reports savings).
Keep only if the reduction is real with no quality loss.
- [ ] **Step 3: (Later, separate) Evaluate llama-swap fronting + rtk-hermes**
Document — do not implement here — the two deferred ideas: (a) llmtrim in front of `172.20.0.1:8090`
via `LLMTRIM_EXTRA_HOSTS` to shrink prompts and speed Pascal prefill (needs validation; unproven for
local OpenAI-compatible backends); (b) `rtk-hermes` (`pre_tool_call` shell rewrite) if the `rtk`
binary is available on Ubuntu.
- [ ] **Step 4: Checkpoint**
No repo commit. Record the decision + measured savings (or rejection) in `memory/hermes-extensions.md`.
`llmtrim uninstall` fully reverses the proxy + CA if rejected.
---
# PHASE 3 — UI trial: stand up BOTH, keep the winner # PHASE 3 — UI trial: stand up BOTH, keep the winner
> Decision resolved (spec §6.1): trial `hermes-ui` (Task 7) **and** `hermes-workspace` (Task 8) in > Decision resolved (spec §6.1): trial `hermes-ui` (Task 7) **and** `hermes-workspace` (Task 8) in
@@ -570,11 +764,14 @@ One UI kept and documented in memory + vault; losers fully removed; repo reflect
## Self-Review (completed) ## Self-Review (completed)
- **Spec coverage:** All 7 repos map to tasks — acp-skill (T2), curator-evolver (T3), camofox (T5), - **Spec coverage:** Original 7 repos — acp-skill (T2), curator-evolver (T3), camofox (T5),
eagle-eye (T6), hermes-ui (T7), hermes-workspace (T8 deploy), with the head-to-head keep-one eagle-eye (T6), hermes-ui (T7), hermes-workspace (T8 deploy) + keep-one decision (T9);
decision in T9; mission-control (explicitly skipped per spec §2.5/§5, no task — intentional). mission-control (skipped per spec §2.5/§5, intentional). **Ecosystem expansion (spec §7)** —
Phase ordering, single-P100 discipline, host-vs-repo boundary, provenance/reversibility, and the hermes-motif (T3b), hermes-web-search-plus (T5b), delegation fabric for cursor+antigravity (T10),
§6 decisions (all resolved 2026-06-27) are reflected. optional llmtrim/rtk context efficiency (T11). Claude Code + Codex install is **done** (T1 Step 3).
Phase ordering, single-P100 discipline, host-vs-repo boundary, provenance (official installers
only — Antigravity URL verified to `antigravity.google`), reversibility, and the §6 decisions are
all reflected.
- **Placeholders:** None of the prohibited kinds. Where a third-party command form can't be verified - **Placeholders:** None of the prohibited kinds. Where a third-party command form can't be verified
remotely (e.g. exact `hermes` subcommand spelling, acp-skill install mechanism, response field remotely (e.g. exact `hermes` subcommand spelling, acp-skill install mechanism, response field
names), the plan's **first step is a concrete "clone + read the README/SKILL.md" command** that names), the plan's **first step is a concrete "clone + read the README/SKILL.md" command** that
docs/superpowers/specs/2026-06-27-hermes-ecosystem-integration-design.md
+92
View File
@@ -252,3 +252,95 @@ Each phase is independently shippable and independently reversible. Stop after a
All four resolved ⇒ **Phases 1, 2, and 3 are all actionable.** The implementation plan that All four resolved ⇒ **Phases 1, 2, and 3 are all actionable.** The implementation plan that
follows details every phase. 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).