diff --git a/.dev/refactor/hermes-integration-plan.md b/.dev/refactor/hermes-integration-plan.md index 085a42f..fccd1c2 100644 --- a/.dev/refactor/hermes-integration-plan.md +++ b/.dev/refactor/hermes-integration-plan.md @@ -39,7 +39,7 @@ For this project, Hermes support should not assume plain OpenAI API keys. Many u ### Expected user flow -Possible final UX: +Possible final UX (now implemented as explicit print/fix/test steps): ```bash npm install -g @cafitac/hermit-agent @@ -62,7 +62,7 @@ hermit install --fix-hermes-mcp hermes mcp test hermit-channel ``` -The `mcp add` syntax has been smoke-checked against the local Hermes CLI help/list behavior. A full `hermes mcp test hermit-channel` round trip remains a later smoke because it depends on local Hermes auth/runtime state. +The `mcp add` syntax and the bounded `hermes mcp test hermit-channel` probe have now been smoke-checked through Hermit's public install helpers. The remaining gap is stronger isolated `HERMES_HOME` automation, not baseline operator readiness. ## Implementation slices @@ -150,6 +150,7 @@ Suggested remaining smoke: Acceptance: - Smoke command and expected output are documented. - If full isolated Hermes model auth is unavailable, separate MCP wiring smoke from provider/auth smoke. +- Public README and setup docs point operators at the explicit print/fix/test sequence. ## Open questions diff --git a/.dev/refactor/roadmap.md b/.dev/refactor/roadmap.md index 5ab00e6..e0ec66c 100644 --- a/.dev/refactor/roadmap.md +++ b/.dev/refactor/roadmap.md @@ -114,6 +114,12 @@ Acceptance: Objective: Hermit can be used from Hermes Agent as an executor lane. +Status: +- Public setup docs now cover Claude Code, Codex, and Hermes Agent separately so each orchestrator path matches the actual setup and runtime boundary. +- Hermes-facing install surfaces exist in three explicit modes: `hermit install --print-hermes-mcp-config`, `hermit install --fix-hermes-mcp`, and `hermit install --test-hermes-mcp`. +- Live runtime delivery remains the existing Hermit MCP server path; the Hermes wrapper is a setup/health adapter, not a second runtime. +- Release smoke has already verified npm and PyPI packages can print, register, and test the Hermes-facing MCP configuration without requiring OpenAI API-key onboarding. + Deliverables: - Hermes-facing setup guidance or installer surface. - Hermes MCP registration or one-shot subprocess bridge, selected by least fragile path. diff --git a/README.md b/README.md index b1fcaab..950f231 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ > Hidden expert. Quiet executor. > -> Hermit is an MCP executor for Claude Code and Codex. Your main agent handles planning, review, and conversation; Hermit quietly handles edits, test runs, refactors, commits, and other mechanical execution on a cheaper local or flat-rate model. +> Hermit is an MCP executor lane for Claude Code, Codex, and Hermes Agent. Your main agent handles planning, review, and conversation; Hermit quietly handles edits, test runs, refactors, commits, and other mechanical execution on a cheaper local or flat-rate model. ## How it works @@ -31,13 +31,13 @@ └──────────────┘ ``` -Claude Code or Codex stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on predictable local or flat-rate execution models. The switch is one word in a slash command: `/foo` → `/foo-hermit`. +Claude Code, Codex, or Hermes Agent stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on predictable local or flat-rate execution models. In Claude Code the switch is often one word in a slash command: `/foo` → `/foo-hermit`. Why Hermit stands out: - Keep your best reasoning model on the work that needs judgment, not boilerplate execution. - Use MCP to turn planner decisions into concrete repo changes, tests, commits, and release operations. - Default to predictable local / flat-rate executor routing instead of silently drifting onto a paid hosted fallback. -- Work with both Claude Code and Codex instead of forcing a single orchestrator stack. +- Work across Claude Code, Codex, and Hermes Agent instead of forcing a single orchestrator stack. ## Why not just use Claude Code or Codex directly? @@ -47,7 +47,7 @@ Why Hermit stands out: | Repetitive repo work | Expensive or token-heavy | Offloaded to a cheaper MCP executor lane | | Multi-step follow-through | Manual context handoff | MCP tasks can carry edits, tests, commits, and release ops through | | Default execution cost | Can drift onto paid hosted models | Defaults to local / flat-rate executor routing | -| Team adoption | Tied to one orchestrator workflow | Works as a shared executor layer across Claude Code and Codex | +| Team adoption | Tied to one orchestrator workflow | Works as a shared executor layer across Claude Code, Codex, and Hermes Agent | Hermit is not trying to replace your orchestrator. It gives you a second lane: use the premium model for judgment, and use Hermit for the mechanical throughput that makes repositories expensive to operate at scale. @@ -73,7 +73,19 @@ npm install -g @cafitac/hermit-agent hermit ``` -Requires Node.js 20+ and Python 3.11+. The npm package bootstraps a managed Python runtime under `~/.hermit/` on first run — no repo checkout needed. If Claude Code or Codex integration is still missing, `hermit` will offer guided setup automatically. You can still run `hermit install` directly when you want to force the full setup/repair flow. For CI or smoke checks that must avoid optional external hook installation, use `hermit install --yes --skip-agent-learner` plus any integration-specific skips you need. For Hermes Agent orchestration, start with the non-mutating snippet: `hermit install --print-hermes-mcp-config`. When you explicitly want Hermit to register itself in Hermes via the Hermes CLI, run `hermit install --fix-hermes-mcp`; then verify the live MCP wiring with `hermit install --test-hermes-mcp`. +Requires Node.js 20+ and Python 3.11+. The npm package bootstraps a managed Python runtime under `~/.hermit/` on first run — no repo checkout needed. If Claude Code or Codex integration is still missing, `hermit` will offer guided setup automatically. You can still run `hermit install` directly when you want to force the full setup/repair flow. + +For CI or smoke checks that must avoid optional external hook installation, use `hermit install --yes --skip-agent-learner` plus any integration-specific skips you need. + +For Hermes Agent orchestration, start with the non-mutating snippet printer: +- `hermit install --print-hermes-mcp-config` — print the exact `hermes mcp add ...` command without editing `~/.hermes` +- `hermit install --fix-hermes-mcp` — explicitly register `hermit-channel` through the Hermes CLI +- `hermit install --test-hermes-mcp` — run Hermes Agent's live `hermes mcp test hermit-channel` probe without changing config + +Setup guides: +- Claude Code: `docs/cc-setup.md` +- Codex: `docs/codex-setup.md` +- Hermes Agent: `docs/hermes-setup.md` To upgrade: `hermit update` @@ -83,13 +95,13 @@ To upgrade: `hermit update` hermit-mcp-server # starts the gateway + MCP stdio server ``` -Then in Claude Code: +Then connect your orchestrator: -``` -/feature-develop-hermit -``` +- Claude Code: see `docs/cc-setup.md`, then run `/feature-develop-hermit ` +- Codex: see `docs/codex-setup.md` +- Hermes Agent: see `docs/hermes-setup.md` -Claude interviews, writes the plan, and delegates implementation to Hermit over MCP. Executor tokens never hit your orchestrator bill. +Claude Code remains the most polished slash-command path today, but all three integrations share the same core idea: the orchestrator does judgment, Hermit does the repetitive repo execution over MCP. ## Reference skills @@ -170,7 +182,9 @@ MIT — see [LICENSE](LICENSE). ## See also - [docs/cc-setup.md](docs/cc-setup.md) — Claude Code MCP registration details -- [docs/hermit-variants.md](docs/hermit-variants.md) — the `-hermit` skill family +- [docs/codex-setup.md](docs/codex-setup.md) — Codex setup, marketplace registration, and runtime verification +- [docs/hermes-setup.md](docs/hermes-setup.md) — Hermes Agent setup, explicit registration, and live MCP smoke checks +- [docs/hermit-variants.md](docs/hermit-variants.md) — the Claude Code `-hermit` skill family - [docs/measure-savings.md](docs/measure-savings.md) — cost-savings measurement protocol - [docs/open-source-positioning.md](docs/open-source-positioning.md) — short public-facing copy for descriptions, releases, and future social previews - [docs/release-notes-template.md](docs/release-notes-template.md) — reusable release-note framing that matches Hermit's planner/executor positioning diff --git a/docs/cc-setup.md b/docs/cc-setup.md index f0778ba..3c2ae21 100644 --- a/docs/cc-setup.md +++ b/docs/cc-setup.md @@ -1,5 +1,7 @@ # Register HermitAgent as a Claude Code MCP sub-agent +This guide is specifically for Claude Code. If you want Codex or Hermes Agent instead, use `docs/codex-setup.md` or `docs/hermes-setup.md`. + This is the setup that makes `/feature-develop-hermit`, `/code-apply-hermit`, etc. work from inside Claude Code. Five minutes, no Docker. ## 1. Install and initialize the gateway diff --git a/docs/codex-setup.md b/docs/codex-setup.md new file mode 100644 index 0000000..fd231e4 --- /dev/null +++ b/docs/codex-setup.md @@ -0,0 +1,83 @@ +# Register HermitAgent as a Codex executor lane + +This guide is specifically for Codex. If you want Claude Code or Hermes Agent instead, use `docs/cc-setup.md` or `docs/hermes-setup.md`. + +## What gets wired + +Hermit's Codex setup currently focuses on setup and health: +- install or refresh the `codex-channels` runtime Hermit expects +- register Hermit in Codex's marketplace/runtime path +- register the `hermit-channel` MCP entry for Codex +- remove the legacy reply hook when present + +Current boundary note: +- The live task runtime still flows through Hermit's existing MCP server and Codex-side runtime path. +- The adapter layer here is about setup/health truthfulness, not a new standalone runtime. + +## 1. Install Hermit + +```bash +npm install -g @cafitac/hermit-agent +hermit +``` + +Requires Node.js 20+ and Python 3.11+. + +## 2. Run the guided install + +For most users, the supported path is: + +```bash +hermit install +``` + +For a non-interactive repair/setup pass: + +```bash +hermit install --yes +``` + +If you are running CI or smoke checks and do not want optional agent-learner hook work: + +```bash +hermit install --yes --skip-agent-learner +``` + +## 3. What success looks like + +A healthy Codex-oriented setup should leave you with: +- a working Hermit managed runtime under `~/.hermit/` +- `codex-channels` runtime installed +- Codex marketplace/runtime registration refreshed when needed +- Codex-facing MCP surface still named `hermit-channel` + +Hermit's doctor and status surfaces should report Codex readiness in setup terms such as `installed` rather than pretending the runtime boundary moved somewhere else. + +## 4. Verification + +Recommended checks: + +```bash +hermit doctor +hermit status +``` + +If setup succeeded but Codex still does not pick the integration up, restart Codex after install so it reloads the refreshed registration. + +## 5. Troubleshooting + +| Symptom | What to do | +|---|---| +| Codex integration reports missing | Re-run `hermit install` or `hermit install --yes`, then check `hermit doctor` | +| Codex still behaves like Hermit is absent after install | Restart Codex so it reloads the refreshed registration | +| You see old reply-hook behavior or stale configuration | Re-run `hermit install`; the current flow removes the legacy Codex reply hook when present | +| You want a Claude Code-style slash command experience | That is still the most polished path today; see `docs/cc-setup.md` and `docs/hermit-variants.md` | + +## 6. Scope clarification + +This document is intentionally narrow: +- it does not claim Codex uses a brand-new Hermit runtime boundary +- it does not replace Codex as planner/reviewer +- it does describe the setup/health surfaces Hermit currently verifies and repairs + +The important operator expectation remains simple: Codex should connect to Hermit through the `hermit-channel` MCP-facing surface while Hermit handles the repetitive repo execution underneath. \ No newline at end of file diff --git a/docs/hermes-setup.md b/docs/hermes-setup.md new file mode 100644 index 0000000..4dfa640 --- /dev/null +++ b/docs/hermes-setup.md @@ -0,0 +1,106 @@ +# Register HermitAgent as a Hermes Agent MCP executor + +This guide is specifically for Hermes Agent. If you want Claude Code or Codex instead, use `docs/cc-setup.md` or `docs/codex-setup.md`. + +## What gets wired + +Hermit exposes a stdio MCP server at: + +```bash +hermit mcp-server +``` + +For Hermes Agent, the important integration surface is the MCP server name `hermit-channel`. Once registered, Hermes can call Hermit's MCP tools such as `run_task`, `reply_task`, `check_task`, and `cancel_task`. + +Current boundary note: +- The live task runtime stays on Hermit's existing MCP server path. +- Hermes-facing setup helpers are for registration, repair, and smoke checks only. + +## 1. Install Hermit + +```bash +npm install -g @cafitac/hermit-agent +hermit +``` + +Requires Node.js 20+ and Python 3.11+. + +## 2. Print the non-mutating registration command + +Start with the safe path: + +```bash +hermit install --print-hermes-mcp-config +``` + +This prints the exact `hermes mcp add ...` command for `hermit-channel` without editing `~/.hermes`. + +## 3. Register Hermit with Hermes Agent + +You have two supported options. + +### Option A — explicit manual registration + +Run the command printed by the previous step. It should look like: + +```bash +hermes mcp add hermit-channel --command hermit --args mcp-server +``` + +### Option B — explicit Hermit-assisted repair/registration + +If you want Hermit to call the Hermes CLI for you: + +```bash +hermit install --fix-hermes-mcp +``` + +This path is intentional and explicit: Hermit does not silently edit Hermes config by default. + +## 4. Verify the live MCP wiring + +Run the bounded live probe: + +```bash +hermit install --test-hermes-mcp +``` + +Under the hood this executes Hermes Agent's live MCP check for `hermit-channel` without mutating config. + +You can also inspect Hermes directly: + +```bash +hermes mcp list +hermes mcp test hermit-channel +``` + +## 5. Troubleshooting + +| Symptom | What to do | +|---|---| +| `hermit install --print-hermes-mcp-config` shows setup text but Hermes still cannot see Hermit | Run the printed `hermes mcp add ...` command or `hermit install --fix-hermes-mcp`, then restart Hermes sessions that should load MCP servers | +| `hermit install --test-hermes-mcp` fails | Run `hermit install --fix-hermes-mcp`, re-check `hermes mcp list`, then retry the test | +| `hermes mcp test hermit-channel` prints an error even though the shell exit code looks successful | Prefer `hermit install --test-hermes-mcp`; Hermit treats known failure text as a failed smoke even when Hermes itself exits 0 | +| You want OAuth-based OpenAI Codex / ChatGPT in Hermes | Configure Hermes itself for `openai-codex` / ChatGPT OAuth; Hermit's MCP registration does not require introducing OpenAI API keys | + +## 6. What this does not change + +- It does not replace Hermes Agent as your planner. +- It does not require Anthropic configuration. +- It does not require OpenAI API keys just to register Hermit as an MCP executor. +- It does not change Claude Code or Codex integrations. + +## Suggested operator flow + +```bash +npm install -g @cafitac/hermit-agent +hermit install --print-hermes-mcp-config +hermes mcp add hermit-channel --command hermit --args mcp-server +hermit install --test-hermes-mcp +``` + +If the manual registration is already done or drifted, swap the middle step for: + +```bash +hermit install --fix-hermes-mcp +``` \ No newline at end of file diff --git a/docs/known-issues.md b/docs/known-issues.md index a45eeea..1460966 100644 --- a/docs/known-issues.md +++ b/docs/known-issues.md @@ -1,30 +1,42 @@ # HermitAgent Known Issues and Stabilization Tasks -> Last updated: 2026-04-18 +> Last updated: 2026-05-01 ## Known Issues ### 1. Waiting Notification Loss [P1] -**Symptom**: When HermitAgent transitions to `waiting` state (e.g., bash permission request, interview question), the notification occasionally fails to surface in the Claude Code session, causing the task to wait indefinitely. +**Symptom**: When HermitAgent transitions to `waiting` state (for example a permission request or interview question), the notification can occasionally fail to surface in the Claude Code session, causing the task to wait longer than expected. -**Cause**: `_send_channel_notification()` uses fire-and-forget — if CC drops the frame at that moment, it is lost. +**Cause**: `_send_channel_notification()` is still fire-and-forget. If Claude Code drops the frame at that exact moment, the notification is lost. -**Solution**: For `waiting` type notifications, retry every 30 seconds until a response is received. Stop retrying on receipt of `running` / `done` / `error`. +**Current mitigation**: Retry logic in `hermit_agent/mcp_server.py` now re-sends `waiting` notifications until the task moves back to `running` or reaches a terminal state. -**Status**: Retry logic implemented in `hermit_agent/mcp_server.py`; continue to monitor in real sessions. +**Status**: Improved but still worth monitoring in real sessions. --- -### 2. /tmp Disk Accumulation [P2] +### 2. Hermes CLI MCP smoke can look successful even when the probe text says otherwise [P1] + +**Symptom**: `hermes mcp test hermit-channel` may print failure or cancellation text while still exiting with status code 0. + +**Why it matters**: Naive shell automation can misread the integration as healthy. + +**Current mitigation**: Hermit's `hermit install --test-hermes-mcp` smoke wraps the Hermes CLI probe and treats known failure text as a failed verification, even when Hermes exits 0. + +**Status**: Public docs now recommend `hermit install --test-hermes-mcp` as the safer readiness check. + +--- + +### 3. /tmp Disk Accumulation [P2] **Symptom**: As Claude Code runs longer, task output files accumulate under `/private/tmp/claude-501/`, eventually causing ENOSPC. -**Cause**: CC captures bash command output to files, but cleanup on session end is suspected to be incomplete. +**Cause**: Claude Code captures bash command output to files, but cleanup on session end appears incomplete. -**Solution**: Identify exact cause, then either file a CC upstream issue or add a periodic cleanup script. +**Next step**: Confirm the exact upstream behavior, then either file a Claude Code issue or add a bounded cleanup helper. -**Status**: Unresolved. Temporarily mitigated by `/tmp` cleanup on restart. +**Status**: Unresolved. Restart-time cleanup is still the temporary mitigation. --- @@ -75,4 +87,5 @@ HERMIT_LLM_URL=http://localhost:8080/v1 ## Recurrence Prevention Notes - **MCP server restart impact**: modifying the MCP server code requires restarting the MCP transport; Claude Code will not auto-reconnect. Prefer applying changes when no tasks are in progress, and use `/mcp` to reconnect if needed. -- **Incorrect cwd**: Passing a parent directory as `cwd` when running `/feature-develop` causes relative-path errors. **Lesson**: set `cwd` to the exact project root (e.g. `$HOME/Project/`), not a parent directory. +- **Incorrect cwd**: Passing a parent directory as `cwd` when running `/feature-develop` causes relative-path errors. Set `cwd` to the exact project root (for example `$HOME/Project/`), not a parent directory. +- **Hermes readiness probes**: when documenting Hermes setup, prefer Hermit's wrapper commands (`--print-hermes-mcp-config`, `--fix-hermes-mcp`, `--test-hermes-mcp`) over raw shell automation that only checks the Hermes CLI exit code. diff --git a/docs/open-source-positioning.md b/docs/open-source-positioning.md index a1e2361..aef4dac 100644 --- a/docs/open-source-positioning.md +++ b/docs/open-source-positioning.md @@ -5,18 +5,18 @@ This file keeps the short public-facing copy for repository metadata, launch pos ## One-line description Primary: -MCP executor layer for Claude Code or Codex that routes repetitive repo work to predictable local or flat-rate models. +MCP executor layer for Claude Code, Codex, or Hermes Agent that routes repetitive repo work to predictable local or flat-rate models. Alternate: -Dedicated MCP execution lane for Claude Code or Codex — keep premium judgment up top, and offload repo mechanics underneath. +Dedicated MCP execution lane for Claude Code, Codex, or Hermes Agent — keep premium judgment up top, and offload repo mechanics underneath. ## Short pitch -Hermit adds a dedicated execution lane to your coding-agent stack. Keep Claude Code or Codex for planning, judgment, and review; let Hermit carry the mechanical repo work through MCP with predictable local or flat-rate routing. +Hermit adds a dedicated execution lane to your coding-agent stack. Keep Claude Code, Codex, or Hermes Agent for planning, judgment, and review; let Hermit carry the mechanical repo work through MCP with predictable local or flat-rate routing. ## What makes Hermit different -- It is not another planner trying to replace Claude Code or Codex. +- It is not another planner trying to replace Claude Code, Codex, or Hermes Agent. - It is an executor layer that turns orchestrator intent into edits, tests, commits, and release follow-through. - It defaults toward cost-predictable local or flat-rate models instead of surprising hosted fallback behavior. - It works across multiple orchestrators, which makes it easier to adopt as shared team infrastructure. @@ -24,7 +24,7 @@ Hermit adds a dedicated execution lane to your coding-agent stack. Keep Claude C ## Audience fit ### Great fit -- Teams already invested in Claude Code or Codex that want a dedicated execution lane. +- Teams already invested in Claude Code, Codex, or Hermes Agent that want a dedicated execution lane. - Repositories where test runs, refactors, commits, and release chores are burning expensive planner tokens. - Maintainers who want one MCP executor path shared across multiple orchestrators. @@ -37,14 +37,14 @@ Hermit adds a dedicated execution lane to your coding-agent stack. Keep Claude C ### Option A Premium reasoning on top, cheap execution underneath. -Hermit is the MCP executor layer for Claude Code and Codex. +Hermit is the MCP executor layer for Claude Code, Codex, and Hermes Agent. ### Option B Keep your best model for judgment. Use Hermit for the repetitive coding work. ### Option C -Claude Code or Codex plans. +Claude Code, Codex, or Hermes Agent plans. Hermit executes. Your bill stays predictable. @@ -55,7 +55,7 @@ Keep the premium orchestrator for judgment. Use Hermit for the repetitive repo work. ### Variant B -Claude Code or Codex thinks. +Claude Code, Codex, or Hermes Agent thinks. Hermit ships the mechanical follow-through. ### Variant C @@ -79,7 +79,7 @@ Use the README hero for in-page explanation of the planner/executor split, and u - Operating guide: `docs/social-preview-ops.md` - Intended use: GitHub social preview image export, release cards, launch posts, and docs screenshots. - Design direction: dark terminal-like card, premium planner on top, cheaper execution lane underneath, no provider-specific billing claims beyond predictable local / flat-rate defaults. -- Message hierarchy: plan with Claude Code or Codex, execute repetitive repo work with Hermit, and reinforce predictable local / flat-rate routing on the supporting side of the card. +- Message hierarchy: plan with Claude Code, Codex, or Hermes Agent, execute repetitive repo work with Hermit, and reinforce predictable local / flat-rate routing on the supporting side of the card. ## Release-note framing diff --git a/docs/release-notes-template.md b/docs/release-notes-template.md index b552158..d62891f 100644 --- a/docs/release-notes-template.md +++ b/docs/release-notes-template.md @@ -48,7 +48,7 @@ Use this template when publishing GitHub Releases, package announcements, or cha ## Reusable opening lines -- Hermit keeps Claude Code or Codex focused on judgment while offloading repetitive repo work to a dedicated MCP executor lane. +- Hermit keeps Claude Code, Codex, or Hermes Agent focused on judgment while offloading repetitive repo work to a dedicated MCP executor lane. - This release sharpens the executor-layer experience: better operator guidance, clearer positioning, and more predictable follow-through. - This update improves the public-facing story around Hermit's planner/executor split without changing its core role.