Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): add Hermes Agent as an MCP-host AI option (#2584)

mike-inkeepbe466bc0ed8c
diff --git a/.changeset/hermes-mcp-support.md b/.changeset/hermes-mcp-support.md
new file mode 100644
index 000000000..5d93d2fe8
--- /dev/null
+++ b/.changeset/hermes-mcp-support.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Add [Hermes Agent](https://hermes-agent.nousresearch.com) (Nous Research) as an MCP-host AI option. `ok init` now detects Hermes (via `~/.hermes/`) and registers the OpenKnowledge server in `~/.hermes/config.yaml` under `mcp_servers`, using the same resilient launcher every other editor gets. Hermes keeps its whole config — models, tool filters, other MCP servers — in that one YAML file, so OK edits only its own `open-knowledge` entry via a format-preserving surgical write (the first YAML host; comments, values, key order, and block formatting are preserved) and declines rather than clobber a config it can't safely parse. Uninstall/repair strip only OK's own entry, leaving a foreign server that shares the key untouched. Like OpenClaw, Hermes is written only when it's actually installed.
diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdx
index 968f64f0e..9c34c851b 100644
--- a/docs/content/get-started/quickstart.mdx
+++ b/docs/content/get-started/quickstart.mdx
@@ -122,7 +122,7 @@ Install the CLI from npm, initialize a project, and start the editor in your bro
npm install -g @inkeep/open-knowledge
# Create (or enter) a project folder, then initialize a knowledge base.
-# `ok init` scaffolds .ok/ and wires up Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw, Pi, and Antigravity.
+# `ok init` scaffolds .ok/ and wires up Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw, Pi, Antigravity, LM Studio, and Hermes.
mkdir my-knowledge-base && cd my-knowledge-base
ok init
diff --git a/docs/content/integrations/hermes.mdx b/docs/content/integrations/hermes.mdx
new file mode 100644
index 000000000..5d4de0784
--- /dev/null
+++ b/docs/content/integrations/hermes.mdx
@@ -0,0 +1,66 @@
+---
+title: Hermes
+description: Use OpenKnowledge with Hermes Agent over MCP.
+icon: custom/Hermes
+---
+
+[Hermes Agent](https://hermes-agent.nousresearch.com) (Nous Research) is a terminal coding agent that connects to MCP servers. Once OpenKnowledge is registered as one, Hermes can read, search, and write your knowledge base through OK's tools — with full attribution, link-awareness, conflict-awareness, and a live browser preview. Inside an OK project, work markdown through those tools rather than native file access, so every edit stays attributed and previewable.
+
+## Install
+
+<McpInstall editor="Hermes">
+
+After `ok init` writes the config, restart Hermes (or run `/reload-mcp` in-session) so it picks up the entry. Hermes auto-discovers MCP tools at startup and updates its tool list at runtime.
+
+</McpInstall>
+
+`ok init` writes the OpenKnowledge server into `~/.hermes/config.yaml` under `mcp_servers`, using the same resilient launcher every other editor gets — it finds `ok` whether you installed the desktop app or the npm CLI, so there's no PATH to configure. Hermes keeps its whole config (models, tool filters, other MCP servers) in that one YAML file, so OK edits only its own `open-knowledge` entry and leaves the rest — your comments included — in place.
+
+<Callout type="info">
+ Hermes is detected by the presence of `~/.hermes/`. If `ok init` shows Hermes as `config root
+ missing; skipped`, launch Hermes once so it creates its home directory, then re-run `ok init`.
+</Callout>
+
+## Initialize a knowledge base
+
+`ok init` turns a folder into a knowledge base (and, on the same run, registers the MCP server above):
+
+```bash
+cd /path/to/your/knowledge-base && ok init
+```
+
+<Callout type="warn">
+ **`ok init` resolves upward into an existing project.** Run inside a subdirectory of an existing
+ OK project, `ok init` finds the *parent* project and refreshes that one — it does not create a
+ nested project, and it writes no markdown in the subdirectory. To create a genuinely separate
+ knowledge base, run `ok init` in a folder that sits **outside any existing `.ok` project tree**.
+</Callout>
+
+## Verify
+
+Start Hermes in the project and ask it to exercise the server:
+
+<VerifyExec subject="Hermes" />
+
+If the agent doesn't see the tool, restart Hermes (or run `/reload-mcp`) — some runtimes lazy-load MCP tools and only surface them after discovery, so absence from the initial list means "not discovered yet," not "not registered."
+
+## Agent contract
+
+The **OpenKnowledge skill** — the authoritative agent contract for tool use, grounding, and linking — is project-scoped, written for Claude, Cursor, Codex, and OpenCode; Hermes has no project skill directory to receive it. So for Hermes agents, the contract is these two reminders:
+
+- **Markdown is MCP-owned.** Inside an OK project, read and write `.md` / `.mdx` through OK's tools (`exec`, `search`, `write`, `edit`, `links`), not native shell or file tools — native access loses attribution and skips the frontmatter, backlinks, and history OK returns.
+- **Discover before concluding the MCP is missing.** Not seeing `exec` in the initial tool list isn't the escape hatch; restart Hermes or run `/reload-mcp` first.
+
+For the complete tool surface, see the [MCP reference](/docs/reference/mcp).
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `ok init` showed Hermes as `config root missing; skipped` | `~/.hermes/` doesn't exist yet, so Hermes wasn't detected | Launch Hermes once (it creates its home directory), then re-run `ok init` |
+| `ok init` reported the config was `left unchanged` | OpenKnowledge declined to edit `~/.hermes/config.yaml` for the reason shown in parentheses | Fix what the reason names (invalid YAML, a duplicated `mcp_servers` key, an oversize config), then re-run `ok init` |
+| Agent doesn't see the `open-knowledge` tools | MCP tools lazy-loaded, or Hermes' process predates the entry | Restart Hermes or run `/reload-mcp` |
+| `write` / `edit` -> "Hocuspocus server is not running" | OK server not started | Run `ok start` (or leave the desktop app running) and retry |
+| Preview "doesn't open" | used the route-only `/#/…` path in a browser | Call `preview_url` for the full URL |
+
+New to OpenKnowledge itself? Start with the [quickstart](/docs/get-started/quickstart) for `ok init` and `ok start`.
diff --git a/docs/content/integrations/meta.json b/docs/content/integrations/meta.json
index 645170460..193ff7f25 100644
--- a/docs/content/integrations/meta.json
+++ b/docs/content/integrations/meta.json
@@ -9,6 +9,7 @@
"pi",
"openclaw",
"antigravity",
- "lm-studio"
+ "lm-studio",
+ "hermes"
]
}
diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx
index 9ce3e95c0..de96c8b78 100644
--- a/docs/content/reference/cli.mdx
+++ b/docs/content/reference/cli.mdx
@@ -22,7 +22,7 @@ npm install -g @inkeep/open-knowledge
## Set up a project
-Run `ok init` in any folder to turn it into an OpenKnowledge project. It scaffolds a `.ok/` directory and registers the OpenKnowledge MCP server with the AI editors it detects on your machine (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw, Pi, Antigravity). It only ever adds its own entry — your other settings, comments, and formatting are left untouched.
+Run `ok init` in any folder to turn it into an OpenKnowledge project. It scaffolds a `.ok/` directory and registers the OpenKnowledge MCP server with the AI editors it detects on your machine (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, OpenClaw, Pi, Antigravity, LM Studio, Hermes). It only ever adds its own entry — your other settings, comments, and formatting are left untouched.
```bash
cd my-project
diff --git a/docs/content/reference/what-open-knowledge-writes.mdx b/docs/content/reference/what-open-knowledge-writes.mdx
index a99ca8e42..732914964 100644
--- a/docs/content/reference/what-open-knowledge-writes.mdx
+++ b/docs/content/reference/what-open-knowledge-writes.mdx
@@ -88,7 +88,7 @@ When you initialize or open a project, the app scaffolds the same project files
| `.claude/skills/`, `.cursor/skills/`, `.codex/skills/`, `.opencode/skills/`, `.pi/skills/` | Project-local "rich" OpenKnowledge skill (`SKILL.md`) for the same five editors | In-project, committed |
| `.ok/skill-targets.json` | Committed list of which editors receive skills, written when you customize the targets | In-project, committed |
| `.claude/launch.json` | Configures Claude Code's preview pane to open the editor (on a local UI port, `39848`) | In-project, committed |
-| `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json`, `~/.openclaw/openclaw.json`, `~/.gemini/config/mcp_config.json` | User-level `open-knowledge` MCP registration, one per detected editor, so it's available in every project (`~/.openclaw/openclaw.json` only when `~/.openclaw/` exists; `~/.gemini/config/mcp_config.json` is Antigravity's shared IDE + `agy` config, only when `~/.gemini/` exists) | Outside-project (editor config) |
+| `~/.claude.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, `~/.config/opencode/opencode.json`, `~/.openclaw/openclaw.json`, `~/.gemini/config/mcp_config.json`, `~/.lmstudio/mcp.json`, `~/.hermes/config.yaml` | User-level `open-knowledge` MCP registration, one per detected editor, so it's available in every project (`~/.openclaw/openclaw.json` only when `~/.openclaw/` exists; `~/.gemini/config/mcp_config.json` is Antigravity's shared IDE + `agy` config, only when `~/.gemini/` exists; `~/.lmstudio/mcp.json` and `~/.hermes/config.yaml` only when those apps are installed) | Outside-project (editor config) |
### While a project is open
@@ -178,6 +178,8 @@ With `--scope user` or `both` (the default), `ok init` also registers the `open-
| `~/.config/opencode/opencode.json` | OpenCode | Outside-project (editor config) |
| `~/.openclaw/openclaw.json` | OpenClaw (only when `~/.openclaw/` exists) | Outside-project (editor config) |
| `~/.gemini/config/mcp_config.json` | Antigravity (only when `~/.gemini/` exists) — shared by the IDE and the `agy` CLI | Outside-project (editor config) |
+| `~/.lmstudio/mcp.json` | LM Studio (only when installed; also checks `~/.cache/lm-studio/mcp.json`) | Outside-project (editor config) |
+| `~/.hermes/config.yaml` | Hermes (only when `~/.hermes/` exists) | Outside-project (editor config) |
Pi is the exception: it has no user-level MCP config (it has no MCP support at all), so its integration is only ever the project-scoped bridge extension above.
diff --git a/docs/src/components/icons/brand.ts b/docs/src/components/icons/brand.ts
index 3b01c9274..7cab2843d 100644
--- a/docs/src/components/icons/brand.ts
+++ b/docs/src/components/icons/brand.ts
@@ -4,6 +4,7 @@ import { ClaudeIcon } from './claude';
import { CodexIcon } from './codex';
import { CursorIcon } from './cursor';
import { GitHubIcon } from './github';
+import { HermesIcon } from './hermes';
import { McpIcon } from './mcp';
import { ObsidianIcon } from './obsidian';
import { OpenClawIcon } from './openclaw';
@@ -22,6 +23,7 @@ export const brandIcons = {
OpenClaw: OpenClawIcon,
Pi: PiIcon,
Antigravity: AntigravityIcon,
+ Hermes: HermesIcon,
GitHub: GitHubIcon,
Obsidian: ObsidianIcon,
MCP: McpIcon,
diff --git a/docs/src/components/icons/hermes.tsx b/docs/src/components/icons/hermes.tsx
new file mode 100644
index 000000000..1f5c22b04
--- /dev/null
+++ b/docs/src/components/icons/hermes.tsx
@@ -0,0 +1,28 @@
+import type { SVGProps } from 'react';
+
+// Hermes Agent brand mark (Nous Research), flattened to a single `currentColor`
+// silhouette so it tracks the sidebar text color and brightens on hover like
+// every other brand icon. viewBox 0 0 24 24 to match Lucide sizing.
+export function HermesIcon(props: SVGProps<SVGSVGElement>) {
+ return (
+ <svg
+ role="img"
+ aria-label="Hermes icon"
+ xmlns="http://www.w3.org/2000/svg"
+ width={24}
+ height={24}
+ fill="currentColor"
+ fillRule="evenodd"
+ viewBox="0 0 24 24"
+ {...props}
+ >
+ <title>Hermes icon</title>
+ <path d="M5.938 12.835c.127-.039.285.02.373.143.028.038.036.092.046.14.003.014-.02.033-.04.05-.124-.098-.24-.194-.354-.291-.011-.01-.016-.027-.025-.042zM8.396 9.412c.195-.032.39-.06.588-.05a.54.54 0 01.148.026c.202.071.402.147.601.224.028.01.05.036.075.055l-.013.027a9.203 9.203 0 01-.26-.089c-.115-.038-.213-.077-.315-.098-.25-.05-.25-.046-.292-.014l.574.144c.275.139.55.276.823.417.042.022.09.057.107.098.026.06.063.076.117.072.066-.006.132-.017.213-.027l-.04.086c.051.08.142.02.216.064-.074.13-.247.09-.334.199l.061.074-.12.087c0 .106-.038.168-.306.243l.026.085-.196.042.07.124h-.25l-.007.137c-.081-.01-.161-.018-.244-.027l-.053.123c-.027-.008-.052-.011-.073-.023-.067-.038-.128-.056-.195.006-.019.017-.063.014-.093.008-.026-.006-.05-.029-.07-.042-.11.095-.11.095-.208.003-.057.046-.12.074-.186.011-.063.027-.123-.02-.178-.014-.07.007-.097-.035-.133-.07l-.13.033c-.013-.236-.194-.19-.34-.203.005-.072.05-.092.095-.094a.474.474 0 01.159.022c.164.05.32.12.496.138.203.021.405.029.601-.015.265-.059.52-.149.707-.365.049-.056.083-.127.117-.195.019-.038.02-.084-.02-.116a1.397 1.397 0 00-.382-.217c.024.12-.031.182-.115.221 0 .014-.004.025 0 .03.08.115.084.16-.007.267a1.39 1.39 0 01-.218.211.477.477 0 01-.641-.05 1.36 1.36 0 01-.133-.152c-.078-.107-.076-.108-.033-.236-.165-.08-.128-.226-.104-.364.008-.05.028-.096.049-.163-.04.014-.067.017-.087.032a.897.897 0 00-.316.357c-.007.016-.01.034-.02.047-.012.015-.034.038-.045.035-.02-.006-.037-.027-.05-.045-.008-.012-.007-.032-.012-.057h-.126l.053-.172a14.82 14.82 0 00-.039-.049l.11-.284c-.06.026-.091.044-.124.051-.03.007-.064 0-.095 0 0-.031-.01-.07.004-.092.149-.22.305-.428.593-.476z"></path>
+ <path d="M8.06 10.788c-.003-.038-.004-.075.037-.062.016.006.034.048.028.067-.01.04-.038.032-.064-.005z"></path>
+ <path
+ clipRule="evenodd"
+ d="M11.981.009c.226-.012.453-.011.679 0 .247.01.495.024.74.062.401.064.798.157 1.19.273.463.138.92.299 1.356.511a7.31 7.31 0 012.948 2.642c.292.469.536.963.739 1.479.219.556.446 1.11.623 1.683.204.654.329 1.326.458 1.997.097.504.182 1.01.29 1.511.156.722.329 1.44.494 2.16.186.812.4 1.615.63 2.415.102.355.193.713.282 1.072.11.436.202.876.254 1.323.031.278.066.557.073.837a7.56 7.56 0 01-.017.88c-.037.413-.1.818-.226 1.212a5.017 5.017 0 01-.915 1.649l-.13.156.018.023c.043-.023.088-.041.127-.068.2-.138.373-.307.531-.49.4-.46.721-.973.975-1.529a3.59 3.59 0 00.325-1.72c-.024-.424-.097-.834-.3-1.213-.013-.027-.015-.06-.03-.121.05.035.082.048.101.072.107.13.22.258.315.398.33.494.46 1.052.486 1.64a3.75 3.75 0 01-.47 1.97c-.36.655-.887 1.14-1.526 1.506-.193.111-.394.21-.595.308-.157.078-.248.211-.318.365a.522.522 0 00-.033.406.359.359 0 01.013.139c-.005.077-.077.155-.14.162-.054.006-.125-.043-.15-.116a1.206 1.206 0 01-.06-.233c-.04-.314-.155-.6-.308-.87a3.906 3.906 0 00-.73-.91 2.129 2.129 0 00-.897-.524 4.093 4.093 0 00-.692-.131c-.075-.008-.15-.04-.22.01.18.06.363.11.538.18.434.173.82.43 1.18.728.308.255.58.543.794.884.098.155.186.315.227.496.027.123.042.25.067.375.013.062-.002.109-.053.144-.047.033-.122.034-.163-.01a.455.455 0 01-.08-.14c-.03-.073-.038-.159-.078-.225a7.314 7.314 0 00-1.423-1.664c-.16-.137-.329-.26-.537-.323-.376-.114-.753-.203-1.15-.154-.213.025-.427.032-.64.053a1.6 1.6 0 00-.736.278 5.14 5.14 0 00-.834.72c-.329.342-.642.699-.955 1.055-.136.155-.264.319-.314.531a5.227 5.227 0 00-.012.051.096.096 0 01-.09.076h-.31c-.046 0-.082-.048-.072-.094.023-.108.045-.216.07-.324.075-.325.19-.635.368-.917.024-.039.04-.088.104-.08l.01.049.027.077c.28-.435.571-.834.996-1.135.283-.204.584-.378.89-.55a.196.196 0 00-.098-.002c-.162.043-.325.084-.485.134-.402.124-.764.33-1.11.566-.147.1-.298.193-.414.333a7.314 7.314 0 00-1.07 1.767.845.845 0 00-.04.12.075.075 0 01-.072.056h-.494c-.04 0-.062-.051-.036-.082.123-.14.246-.282.377-.415.275-.281.58-.532.777-.884.027-.048.063-.09.095-.135.238-.333.54-.607.818-.902.082-.086.175-.16.26-.24.029-.027.053-.057.079-.085l-.018-.025-.135.041c-.034.017-.07.031-.102.05-.248.144-.494.292-.743.433-.408.23-.825.439-1.209.711-.281.2-.591.358-.889.533-.02.012-.044.015-.08.028-.015-.135.143-.201.108-.336-.033.014-.064.02-.085.038-.111.096-.227.19-.328.296-.148.157-.284.325-.425.488-.125.143-.25.286-.373.431A.153.153 0 019.89 24H8.762a.316.316 0 00.016-.042c.028-.09.085-.172.083-.28-.091-.018-.162.001-.212.077a4.45 4.45 0 00-.136.215c-.01.016-.024.03-.042.03h-.093c-.019 0-.029-.022-.017-.037.071-.088.14-.178.209-.268.001-.002-.006-.012-.012-.024-.014.004-.03.006-.045.013-.176.09-.352.181-.527.274a.363.363 0 01-.168.042H5.202c-.026 0-.039-.036-.019-.053.21-.178.402-.374.558-.605.335-.496.538-1.047.667-1.629.004-.02-.003-.043-.006-.091-.037.048-.059.072-.076.1a1.943 1.943 0 01-.334.415c-.28.258-.59.448-.983.464-.297.012-.588 0-.865-.127-.46-.21-.722-.57-.794-1.072-.025-.17-.017-.171-.182-.219A3.513 3.513 0 011.97 20.6a2.286 2.286 0 01-.808-1.13 3.569 3.569 0 01-.16-1.245c.002-.034.016-.067.024-.1.032.023.046.043.05.066.033.153.059.308.096.46.086.355.257.664.516.92.258.256.571.419.91.532.358.118.717.138 1.07-.016a1.89 1.89 0 00.621-.452c.328-.348.533-.76.648-1.223.009-.034.005-.071.007-.11-.015.006-.026.006-.03.011-.031.05-.064.1-.093.152-.284.502-.679.887-1.196 1.135-.351.17-.718.255-1.11.159a1.607 1.607 0 01-.971-.64 2.006 2.006 0 01-.368-.924 2.903 2.903 0 01.02-.886c.05-.439.466-1.17.742-1.271-.02.063-.035.112-.053.16-.043.116-.097.227-.13.345a1.901 1.901 0 00-.05.82c.033.212.09.416.204.6.147.236.346.407.62.465.11.023.225.014.338.018a.576.576 0 00.386-.131c.164-.128.282-.292.366-.481.168-.375.24-.777.309-1.179.05-.296.093-.594.133-.893.039-.281.071-.563.104-.845.026-.232.048-.464.074-.696.024-.228.052-.455.076-.683.024-.227.047-.455.069-.683.013-.14.022-.28.034-.42l.037-.417c.022-.25.041-.5.065-.748.008-.082-.02-.132-.09-.177a2.46 2.46 0 01-.492-.418c-.1-.109-.188-.228-.282-.342-.035-.042-.056-.097-.116-.118a2.084 2.084 0 00.275.597c.06.092.131.176.196.265.063.086.182.115.234.226-.028.003-.046.01-.06.006a4.74 4.74 0 01-.22-.057 2.71 2.71 0 01-1.287-.819c-.435-.487-.656-1.076-.71-1.723a5.206 5.206 0 01.014-1.06c.072-.602.22-1.186.45-1.745.155-.376.338-.741.526-1.102.205-.393.466-.75.765-1.076.512-.559 1.104-1.024 1.726-1.448.717-.49 1.478-.898 2.277-1.233C8.244.828 8.767.632 9.31.494c.655-.166 1.31-.33 1.982-.415.229-.03.458-.058.688-.07zm-1.847 22.82c-.07.06-.147.111-.207.18-.238.27-.464.549-.668.869l-.044.108a.177.177 0 00.093-.057c.174-.19.351-.378.519-.574.104-.122.195-.255.288-.386.024-.034.03-.08.046-.12l-.027-.02zm1.65-3.695a5.51 5.51 0 00-.653.593l-.37.386a.963.963 0 01-.377.25 1.372 1.372 0 01-.467.09c-.044 0-.087.006-.151.012.028.058.043.097.064.131.15.242.301.482.45.724.136.22.276.438.399.666.068.125.105.267.156.404.077.027.14-.018.202-.048.29-.135.579-.274.867-.412.213-.101.437-.186.636-.31.347-.215.68-.455 1.018-.685.015-.01.026-.028.042-.046-.023-.019-.038-.037-.056-.044-.287-.111-.527-.3-.77-.482a5.319 5.319 0 01-.506-.42 1.757 1.757 0 01-.41-.653c-.019-.049-.045-.095-.075-.156zm-5.847.264c-.06.096-.097.194-.132.293a3.38 3.38 0 01-.555 1.01c-.2.25-.455.412-.762.493-.23.06-.464.076-.7.07-.048-.002-.097.002-.158.005.016.04.021.066.035.085.1.145.23.246.4.295.157.046.316.034.498.023.181-.037.343-.115.485-.234.238-.199.402-.454.536-.732.175-.363.264-.751.342-1.144.01-.053.008-.11.011-.164zm14.945-4.586c.008.029.016.057.027.107.024.155.051.31.072.464.03.219.067.437.078.657.017.344.027.689-.014 1.033-.037.315-.063.633-.116.946a6.153 6.153 0 01-.46 1.518c-.008.018-.01.039-.02.082.047-.03.077-.042.098-.064.085-.083.17-.167.248-.255.271-.305.458-.66.596-1.043.18-.498.228-1.011.145-1.531-.103-.65-.33-1.263-.597-1.881a9.055 9.055 0 00-.024-.055l-.033.022zM5.797 8.29a.26.26 0 00.018.153c.124.251.25.501.379.75.025.049.066.09.03.163-.284.06-.578.119-.88.255.059.038.097.06.132.087.042.032.112.058.09.12-.01.033-.075.048-.117.072.017.01.043.021.067.036.166.102.33.207.447.368.138.192.229.404.188.644-.079.469-.306.85-.69 1.132-.054.04-.106.083-.161.122a.243.243 0 00-.103.245.77.77 0 00.055.195c.083.196.22.35.375.492.083.076.159.164.222.257a.37.37 0 01.025.377c-.023.05-.05.099-.076.148-.03.06-.028.111.022.162.041.042.08.089.112.138.038.058.078.079.147.05a.486.486 0 01.333-.006c.16.046.302.126.444.21.13.077.264.149.4.219.067.035.14.05.219.026.071-.022.124.01.145.076.02.064-.003.108-.074.139-.07.03-.137.063-.209.088-.1.035-.201.073-.314.077-.013-.107.11-.088.127-.159-.206-.126-.643-.145-.801-.034.063.112.035.21-.096.313-.13-.1-.025-.202.002-.3a.209.209 0 00-.249.17c-.015.101.067.216.178.224.108.007.218-.005.326-.012.06-.005.12-.027.199 0-.103.123-.248.127-.357.19.002.05.07.086.019.131-.053.048-.095-.001-.132-.03-.08-.063-.16-.126-.231-.197a.474.474 0 01-.157-.311.52.52 0 00-.043-.172c-.032-.074-.032-.137.033-.19-.018-.03-.028-.053-.045-.072a1.222 1.222 0 01-.196-.369c-.053-.137-.046-.264.048-.381.024-.03.05-.06.064-.095a.664.664 0 00.047-.168c.017-.165-.064-.287-.182-.387-.186-.156-.36-.322-.46-.551-.005-.011-.024-.017-.037-.026-.011.017-.024.027-.025.038-.019.185-.045.37-.052.557-.014.377.058.743.162 1.104.118.41.289.798.488 1.173.267.502.537 1.002.812 1.5.055.098.13.189.208.27.198.202.452.272.724.273.202 0 .404-.006.605-.026.295-.03.59-.073.884-.113.183-.025.365-.057.548-.08.21-.026.38.073.522.21.16.156.305.327.447.5.22.265.397.56.554.867.05.098.07.1.147.03.13-.121.26-.242.394-.36.067-.059.088-.12.067-.213a3.535 3.535 0 01-.085-.796c.002-.157.006-.314.018-.471.015-.224.03-.45.06-.672a59.114 59.114 0 01.362-2.298c.087-.493.182-.984.268-1.477.06-.347.118-.694.162-1.043.034-.273.055-.55.063-.825.011-.332.003-.665.002-.998 0-.077.004-.155-.01-.23-.028-.142-.01-.155-.162-.19a5.826 5.826 0 00-.607-.107c-.146-.018-.207-.053-.221-.19-.006-.049-.025-.098-.041-.146-.009-.025-.024-.048-.046-.09l-.025.264c-.009.096-.029.116-.127.115-.055 0-.11-.008-.164-.008-.476 0-.952-.008-1.426.032-.095.008-.173-.015-.226-.103-.04-.066-.088-.126-.134-.186-.063-.084-.086-.093-.182-.06-.195.068-.388.138-.582.21a2.71 2.71 0 00-.675.394.986.986 0 01-.323.168c-.033.01-.07.008-.127.013.02-.066.024-.114.047-.15.064-.105.135-.205.205-.306.023-.033.049-.063.073-.095l-.015-.023-.201.037c-.146.04-.296.07-.437.122-.148.053-.266.023-.386-.072a3.623 3.623 0 01-.733-.786l-.093-.132zm8.592 8.963l-.147.09c-.22.134-.44.266-.659.402-.093.058-.184.12-.27.188-.085.07-.124.161-.072.272.047.1.093.2.147.294.047.08.124.138.213.147.11.01.228.012.336-.012.217-.05.372-.205.528-.357a.291.291 0 00.087-.308c-.046-.18-.079-.365-.118-.547-.011-.052-.027-.103-.045-.169zm-.257-2.409c-.12.291-.205.597-.325.91-.151.433-.294.87-.435 1.323.036-.01.054-.01.067-.018.261-.16.522-.324.785-.484.054-.033.071-.078.065-.138-.012-.13-.024-.262-.034-.393l-.068-.886c-.008-.103-.02-.206-.029-.31-.009 0-.017-.002-.026-.004zm3.081-8.13l.099.285c.08.231.159.463.24.714l.58 1.952c.187.63.372 1.262.558 1.893.114.382.235.762.343 1.146.072.257.126.519.186.799.044.206.087.413.127.64.034.106.023.226.077.325l.025-.006-.068-.362c-.038-.206-.077-.412-.113-.638-.015-.07-.029-.141-.046-.211-.095-.396-.177-.796-.29-1.187-.196-.685-.413-1.364-.618-2.046-.165-.549-.322-1.1-.488-1.648-.069-.227-.15-.45-.226-.695l-.117-.336c-.037-.107-.075-.216-.115-.322-.04-.106-.084-.21-.127-.314a7.558 7.558 0 01-.027.01zM6.225 14.304c-.063-.001-.115.014-.134.083a.35.35 0 00.41.012 4.533 4.533 0 00-.276-.095zM5.23 11.98c-.026-.027-.057-.048-.075.002-.012.032-.007.07-.01.113.082-.037.082-.037.085-.115zm.062-1.189a.135.135 0 00-.088.056.197.197 0 00-.025.11c.005.152.01.306.026.457a.751.751 0 00.066.218c.061.136.157.167.288.101.055-.027.06-.054.025-.11a4.52 4.52 0 01-.129-.211c-.015-.068-.066-.131-.033-.207.04-.09-.076-.116-.074-.19V10.874c-.003-.038-.006-.087-.056-.083zm-.017-.968a.867.867 0 00-.467.127c-.076.045-.084.07-.05.158.034.087.07.173.115.254.064.117.09.125.21.077a.657.657 0 01.336-.053c.202.022.357.136.504.264l.092.077c.007-.006.014-.013.022-.018-.019-.105-.035-.226-.149-.264-.157-.053-.324-.075-.508-.117l-.24-.005c.24-.169.452-.044.687.009-.063-.115-.153-.147-.23-.193-.082-.05-.17-.092-.25-.144-.06-.037-.12-.08-.072-.172zm10.233.325c-.23-.01-.427.08-.608.211-.034.026-.06.065-.105.117.087.026.15.046.232.065.044-.015.088-.03.13-.046.306-.114.61-.115.904.031.126.063.237.04.366-.005-.02-.031-.03-.054-.045-.071a.986.986 0 00-.448-.273c-.14-.044-.284-.024-.426-.03zM7.99 6.483a.308.308 0 00.002.133c.08.321.156.643.242.962.104.387.27.75.456 1.103.02.037.061.08.098.087a.404.404 0 00.253-.051l-.472-.84c-.23-.448-.405-.92-.579-1.394zM10.397.497c-.2-.008-.405.004-.603.034-.236.035-.47.087-.7.152-.287.08-.569.18-.852.273-.04.013-.074.038-.11.058.028.014.05.018.07.014.287-.068.58-.085.873-.09.134-.002.269.009.402.025.19.024.382.048.57.09.456.104.874.3 1.265.556.464.306.888.66 1.257 1.078.205.232.395.475.56.739.17.274.315.561.449.856.273.601.456 1.232.6 1.876.04.173.07.348.1.524.017.104.065.167.17.19.122.028.2.105.22.251-.003.102-.06.174-.129.24a1.065 1.065 0 00-.268.358.164.164 0 00.083-.039c.08-.086.162-.172.235-.265a.56.56 0 00.13-.333c.009-.05.022-.1.024-.15.007-.124-.017-.15-.143-.168-.025-.004-.049-.014-.073-.015-.082-.007-.125-.063-.137-.131-.033-.198-.004-.355.247-.408.086-.018.174-.03.26-.042.158-.023.315-.053.473-.067.14-.012.19.033.226.167.008.029.018.057.021.087.019.179-.008.225-.141.288-.027.013-.055.024-.078.042a.148.148 0 00-.051.067c-.039.144.073.382.206.445l.673.32c.023.011.05.015.075.023l.018-.026c-.015-.008-.032-.013-.044-.024a2.27 2.27 0 00-.544-.32 4.898 4.898 0 00-.173-.075.203.203 0 01-.126-.191c-.003-.085.045-.154.128-.187l.059-.025c.099-.044.118-.076.112-.187a.384.384 0 00-.008-.063c-.067-.294-.123-.59-.205-.88a9.478 9.478 0 00-.826-2.036 7.465 7.465 0 00-1.39-1.805 4.536 4.536 0 00-1.177-.824 3.656 3.656 0 00-1.016-.328 6.155 6.155 0 00-.712-.074zm6.719 5.955c.01.014.018.028.038.034l-.022-.044-.016.01zM4.103 3.917a.062.062 0 01-.03.012.455.455 0 01-.04.039c-.01.01-.02.02-.045.04l-.363.354c-.088.085-.17.178-.266.253-.284.22-.425.53-.544.855a.132.132 0 00-.007.071c.013.055.033.108.052.168l.074.026c-.017.056-.03.105-.047.152-.058.164-.118.327-.175.491-.005.015.008.036.019.077.08-.175.158-.33.225-.489.228-.544.484-1.074.819-1.561.09-.133.182-.266.283-.401.004-.006.007-.013.022-.03.001-.016.003-.032.015-.04l.008-.017zm12.976 2.408a.023.023 0 01.009.019.073.073 0 00-.006.01.188.188 0 00.007.02l.018.022c.002-.007.007-.016.005-.021-.003-.01-.012-.018-.02-.038a1.331 1.331 0 01-.013-.012zM4.199 4.48c-.003.004-.008.008-.027.014-.005.013-.011.025-.031.047a2.085 2.085 0 01-.124.167c-.048.07-.116.055-.181.041-.134-.028-.228.016-.287.143-.089.187-.187.37-.273.56-.049.108-.11.216-.118.36.081.003.154.007.228.008h.228a2.563 2.563 0 01-.079.264c-.01.052-.022.103-.033.155l.02.004c.018-.046.037-.092.067-.153.066-.142.13-.285.2-.426.02-.04.034-.1.116-.092 0 .043.004.084 0 .124-.005.045-.017.09-.028.143.141.043.086.174.115.269.102-.022.104-.195.248-.144v.205l.017.002.439-1.059c-.13 0-.246-.02-.358.033-.024.011-.058-.001-.108-.004.075-.15.139-.278.211-.417a.128.128 0 01.025-.036c0-.015-.001-.03.008-.038l.006-.02c-.005.006-.01.011-.028.017-.004.012-.009.024-.026.045a.085.085 0 01-.032.033c-.123.157-.09.164-.258.106-.079-.027-.078-.028-.047-.144.028-.046.056-.093.098-.15 0-.016-.001-.032.007-.042L4.2 4.48zm2.073-.67c-.003.006-.007.011-.027.016-.094.125-.194.246-.28.377-.155.238-.301.481-.451.723-.14.224-.345.368-.575.481-.017.008-.04.006-.079.011.012-.059.016-.109.033-.153a6.076 6.076 0 01.229-.518l-.007-.02a.138.138 0 01-.035.025c-.028.05-.055.1-.093.164-.26.424-.443.817-.442.95.024.004.048.011.073.013.177.013.188.007.26-.165.03-.07.077-.12.147-.15l.175-.07c.044-.018.085-.057.146-.032.003.05-.01.11.014.145.042.062.044.125.047.193.002.049.017.098.026.147.029-.034.039-.065.05-.097.142-.39.277-.782.428-1.17.1-.256.22-.504.33-.756.013-.03.013-.067.03-.092V3.81zm3.987-.34c0 .045.01.084.021.123.042.16.094.318.124.48.024.133.023.27.028.406 0 .033-.019.067-.032.11-.094-.058-.047-.158-.106-.215h-.125c-.015.072-.01.152-.046.2-.066.085-.155.154-.236.227-.043.038-.078.018-.103-.025l-.046-.087c-.065.035-.117.069-.172.093-.116.051-.235.095-.35.147-.085.038-.09.053-.07.147.014.075.034.148.047.223.013.072.05.109.123.124.233.05.462.115.657.265.058-.102.058-.102.168-.151.03-.014.06-.03.092-.042.08-.03.115-.017.15.06.023.048.041.098.066.158.06-.14-.042-.267.017-.416.157.18.24.39.375.567a.235.235 0 00.022-.098c.002-.124 0-.247.002-.371 0-.034.013-.067.02-.1l.032-.003c.11.155.13.354.226.52a3.036 3.036 0 00-.01-.392c-.004-.045 0-.074.05-.088.08.036.116.14.215.158-.03-.275-.423-1.137-.798-1.635-.114-.127-.2-.28-.34-.386zm-2.667.696c-.019.034-.03.05-.037.067-.061.185-.125.37-.18.556-.031.105-.087.169-.195.19-.09.019-.178.052-.268.073-.038.009-.089.015-.118-.003-.024-.016-.025-.069-.036-.106-.064.076-.082.087-.17.047-.133-.062-.262-.135-.393-.201-.048-.025-.093-.063-.17-.03-.043.12-.091.25-.137.382-.099.28-.087.242.095.453.046.048.102.03.154.023.054-.009.106-.03.16-.036.13-.013.26-.08.367-.015.204-.064.387-.122.571-.178.05-.015.089.005.114.054.022.042.034.093.082.121.038-.056-.013-.128.063-.178l.14.241-.042-1.46zm.278.358c-.096-.01-.107.01-.11.108-.002.038-.003.078.002.115.03.2.099.386.174.57.002.006.012.01.022.015l.078-.05c.052.036.081.088.153.088.205-.002.41.014.616.012.099-.001.158.042.205.12.018.03.024.077.088.066l-.08-.394c-.05-.195-.085-.395-.172-.589-.057.057-.114.068-.18.046a.72.72 0 00-.135-.028c-.22-.028-.44-.059-.66-.08zm10.254-1.727c.089.163.155.316.139.491-.016.168.026.342-.044.516-.047-.033-.088-.082-.112-.075-.117.035-.164-.057-.227-.115a4.772 4.772 0 01-.286-.29l-.104-.113a4.856 4.856 0 01-.023.019c.035.046.07.093.11.156.04.064.084.127.122.193.034.058.065.118.031.205-.082-.01-.164-.019-.246-.032-.06-.01-.101 0-.124.07-.031.098-.037.096-.15.09.02.042.036.08.057.116.041.074.03.138-.03.196-.06.06-.118.122-.178.181a.175.175 0 01-.185.046c-.222-.061-.447-.113-.67-.174-.032-.009-.063-.04-.086-.068-.03-.04-.052-.087-.08-.13-.044-.07-.09-.138-.136-.207a.18.18 0 00-.014.105c.012.127.03.253.035.38.005.1-.024.12-.121.104-.104-.017-.206-.04-.31-.058-.064-.012-.131-.028-.202.03l.081.208c.09 0 .166-.01.237.002a.819.819 0 01.458.251c.078.083.154.168.241.26l.018-.005c-.004-.006-.008-.013-.01-.04.014-.056-.062-.118.018-.178.031.03.064.057.088.09.058.078.111.159.169.257l.089.141.024-.013a2093.819 2093.819 0 01-.427-.934c.055.007.083.007.108.016.193.07.385.142.577.216.074.028.147.06.219.094.062.028.112.018.157-.033.05-.056.102-.112.154-.167.05-.051.095-.046.132.014.016.025.026.053.04.08.071.138.143.277.217.433l.159.308.025-.011c-.044-.106-.07-.218-.138-.334-.057-.182-.168-.346-.206-.545.136.034.362.326.567.732l.057.074.018-.011a1.563 1.563 0 01-.052-.127c-.046-.145-.097-.29-.136-.436-.022-.083-.036-.173.022-.26l.109.058-.026-.207.027-.016c.022.02.05.036.065.06.073.108.143.22.215.33.01.016.029.029.043.043-.036-.217-.2-.38-.229-.626l.155.112c.014-.166.012-.319.042-.465.032-.158-.023-.297-.063-.445.024.004.036.006.055.025.092.124.183.249.277.371.02.027.05.047.069.087l.04.063.019-.015a.293.293 0 01-.053-.082 27.922 27.922 0 01-.332-.49c-.221-.311-.363-.467-.485-.521zm-6.57.327c-.003.161.092.275.069.415l-.368.087c.09.139.032.237-.052.331-.05.057-.092.122-.143.178-.037.04-.046.078-.018.126l.16.275c.029.048.072.066.128.064.076-.003.152 0 .228-.001.116-.003.216.022.275.137.006.014.02.024.044.052.004-.059-.003-.098.01-.13.016-.04.04-.099.072-.108.084-.023.173-.024.26-.03.013-.001.027.018.04.029l.071.065c.019-.11-.082-.198-.024-.31l.126.04c-.026-.123-.07-.245-.071-.366 0-.123.051-.243.115-.36.107.062.16.156.234.253.183.265.36.533.494.834.165-.078.27.068.407.088-.003-.106-.133-.441-.197-.492a.142.142 0 00-.102-.028c-.06.011-.119.039-.191.063-.025-.039-.056-.078-.077-.122a3.936 3.936 0 00-.473-.783c-.076-.094-.16-.182-.228-.26l-.391.285c-.049.035-.094.03-.132-.017l-.169-.207c-.025-.03-.053-.059-.097-.108z"
+ ></path>
+ </svg>
+ );
+}
diff --git a/packages/cli/src/commands/editors.test.ts b/packages/cli/src/commands/editors.test.ts
index dbee35dcd..c40cfa42f 100644
--- a/packages/cli/src/commands/editors.test.ts
+++ b/packages/cli/src/commands/editors.test.ts
@@ -19,6 +19,7 @@ import {
resolveCodexConfigPath,
resolveCursorConfigPath,
resolveEditorTargets,
+ resolveHermesConfigPath,
resolveLmStudioConfigPath,
resolveOpenClawConfigPath,
resolveOpenCodeConfigPath,
@@ -218,6 +219,17 @@ describe('resolveAntigravityConfigPath', () => {
});
});
+describe('resolveHermesConfigPath', () => {
+ it('builds the global Hermes config path (home-relative on every platform)', () => {
+ expect(resolveHermesConfigPath({ home: '/Users/alice', platformName: 'darwin' })).toBe(
+ '/Users/alice/.hermes/config.yaml',
+ );
+ expect(resolveHermesConfigPath({ home: '/home/alice', platformName: 'linux' })).toBe(
+ '/home/alice/.hermes/config.yaml',
+ );
+ });
+});
+
describe('resolvePiAgentDirPath', () => {
it('builds the default Pi agent dir under home', () => {
expect(resolvePiAgentDirPath({ home: '/Users/alice', platformName: 'darwin', env: {} })).toBe(
diff --git a/packages/cli/src/commands/editors.ts b/packages/cli/src/commands/editors.ts
index ba8fa6b4c..8486fbf77 100644
--- a/packages/cli/src/commands/editors.ts
+++ b/packages/cli/src/commands/editors.ts
@@ -610,6 +610,20 @@ export function resolveOpenClawConfigPath(options: AppSupportOptions = {}): stri
return pathApiForPlatform(platformName).join(home, '.openclaw', 'openclaw.json');
}
+/**
+ * Hermes Agent (Nous Research) keeps its WHOLE config — models, tool filters,
+ * MCP servers — at a user-global `~/.hermes/config.yaml` on every platform, with
+ * servers nested under the top-level `mcp_servers` key. It is YAML, so OK edits
+ * it through the format-preserving `yaml` document writer (the JSON/TOML surgical
+ * siblings don't apply), touching only its own entry so the user's model + tool
+ * config and comments in that same file are byte-preserved.
+ */
+export function resolveHermesConfigPath(options: AppSupportOptions = {}): string {
+ const platformName = options.platformName ?? process.platform;
+ const home = options.home ?? homedir();
+ return pathApiForPlatform(platformName).join(home, '.hermes', 'config.yaml');
+}
+
/**
* Pi's coding-agent home dir — `~/.pi/agent/` (settings, global extensions,
* skills, sessions), overridable via `PI_CODING_AGENT_DIR` like Codex's
@@ -688,14 +702,15 @@ export interface EditorMcpTarget {
*/
configPath: (cwd: string, home?: string) => string;
/**
- * On-disk config format for this editor. `'json'` / `'toml'` entries go
- * through the surgical entry upsert; `'file'` means OK owns the WHOLE file
- * (Pi's bridge extension) — the write path drops
+ * On-disk config format for this editor. `'json'` / `'toml'` / `'yaml'`
+ * entries go through the surgical entry upsert (each preserving the host
+ * config's comments + formatting via its own document model); `'file'` means
+ * OK owns the WHOLE file (Pi's bridge extension) — the write path drops
* `buildPiExtensionSource(...)` verbatim and classify/removal treat the raw
* text (via the synthetic `PI_MANAGED_FILE_ENTRY_COMMAND` entry) instead of
* parsing a server map. `topLevelKey` is inert for `'file'` targets.
*/
- format: 'json' | 'toml' | 'file';
+ format: 'json' | 'toml' | 'yaml' | 'file';
/** Top-level key that holds the server map. */
topLevelKey: 'mcpServers' | 'servers' | 'mcp_servers' | 'mcp';
/**
@@ -906,6 +921,28 @@ export const EDITOR_TARGETS: Record<EditorId, EditorMcpTarget> = {
// like OpenClaw. Writing a config for an absent app is a pointless no-op.
offerOnlyWhenDetected: true,
},
+ hermes: {
+ id: 'hermes',
+ label: EDITOR_LABELS.hermes,
+ configPath: (_cwd, home) => resolveHermesConfigPath({ home }),
+ // YAML config: OK edits only its own `mcp_servers.open-knowledge` entry via
+ // the format-preserving `yaml` document writer, so the user's model +
+ // tool-filter config and comments in the same file are untouched.
+ format: 'yaml',
+ topLevelKey: 'mcp_servers',
+ serverName: () => MCP_SERVER_NAME,
+ // The resilient stdio chain (`command`/`args`) drops into Hermes' stdio
+ // server shape unchanged — only the YAML envelope differs from the other
+ // hosts, exactly like OpenClaw reuses this builder under a different key.
+ buildEntry: (_cwd, options) => buildManagedServerEntry(options),
+ scope: 'global',
+ detectPath: (_cwd, home) => join(home ?? homedir(), '.hermes'),
+ // Never write `~/.hermes/config.yaml` unless Hermes is actually installed —
+ // gated on detection even under the consent-flow skipAvailabilityCheck, like
+ // OpenClaw. A niche global agent most users don't run; an orphan config that
+ // nothing reads helps no one.
+ offerOnlyWhenDetected: true,
+ },
};
/**
diff --git a/packages/cli/src/commands/init.test.ts b/packages/cli/src/commands/init.test.ts
index 2def10918..c67466a6f 100644
--- a/packages/cli/src/commands/init.test.ts
+++ b/packages/cli/src/commands/init.test.ts
@@ -14,6 +14,7 @@ import {
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { readBundleDecision } from '@inkeep/open-knowledge-server';
+import { parse as parseYaml } from 'yaml';
import { loadConfig } from '../config/loader.ts';
import { OK_DIR } from '../constants.ts';
import { previewContent } from '../content/preview.ts';
@@ -809,6 +810,8 @@ describe('runInit', () => {
mkdirSync(join(fakeHome, '.gemini'), { recursive: true });
// LM Studio is likewise `offerOnlyWhenDetected` — create its config dir.
mkdirSync(dirname(lmStudioConfigPath()), { recursive: true });
+ // Hermes is likewise `offerOnlyWhenDetected` — gated on `~/.hermes`.
+ mkdirSync(join(fakeHome, '.hermes'), { recursive: true });
const result = await runInitForTest({ editors: [...ALL_EDITOR_IDS] });
@@ -838,6 +841,11 @@ describe('runInit', () => {
readFileSync(join(fakeHome, '.gemini', 'config', 'mcp_config.json'), 'utf-8'),
);
expect(antigravityConfig.mcpServers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
+ // Hermes is YAML under `mcp_servers` — verify the entry landed there.
+ const hermesConfig = parseYaml(
+ readFileSync(join(fakeHome, '.hermes', 'config.yaml'), 'utf-8'),
+ );
+ expect(hermesConfig.mcp_servers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
});
it('overwrites across all targeted editors', async () => {
@@ -2434,6 +2442,7 @@ describe('detectInstalledEditors', () => {
mkdirSync(join(fakeHome, '.pi', 'agent'), { recursive: true });
mkdirSync(join(fakeHome, '.gemini'), { recursive: true });
mkdirSync(dirname(lmStudioConfigPath()), { recursive: true });
+ mkdirSync(join(fakeHome, '.hermes'), { recursive: true });
const detected = detectInstalledEditors(testDir, fakeHome);
expect(detected).toEqual(expect.arrayContaining([...ALL_EDITOR_IDS]));
expect(detected).toHaveLength(ALL_EDITOR_IDS.length);
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index a60c37b6f..de668baab 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -54,6 +54,7 @@ import {
parseTree as parseJsoncTree,
} from 'jsonc-parser';
import { stringify as stringifyToml } from 'smol-toml';
+import { isCollection, parseDocument, stringify as stringifyYaml } from 'yaml';
import { CONFIG_FILENAME, OK_DIR } from '../constants.ts';
import { formatPreviewBlock, type PreviewResult } from '../content/preview.ts';
import { buildPiExtensionSource, makePiManagedFileEntry } from '../integrations/pi-extension.ts';
@@ -173,6 +174,18 @@ function writeTomlConfig(path: string, config: Record<string, unknown>): void {
atomicWriteFileSync(path, serialized.endsWith('\n') ? serialized : `${serialized}\n`);
}
+/**
+ * Write the config to disk as YAML with a trailing newline. Same
+ * atomic-write + caller-owns-mkdir contract as `writeJsonConfig`. Only the
+ * absent/blank case reaches this — a present Hermes `config.yaml` is edited
+ * surgically via the `yaml` document model so the user's model + tool config
+ * and comments in the same file survive.
+ */
+function writeYamlConfig(path: string, config: Record<string, unknown>): void {
+ const serialized = stringifyYaml(config);
+ atomicWriteFileSync(path, serialized.endsWith('\n') ? serialized : `${serialized}\n`);
+}
+
// ---------------------------------------------------------------------------
// Surgical JSON/JSONC upsert — touch only OK's own entry
// ---------------------------------------------------------------------------
@@ -431,6 +444,103 @@ function upsertTomlMcpConfig(
return { kind: result.existed ? 'overwritten' : 'written' };
}
+// ---------------------------------------------------------------------------
+// Format-preserving YAML upsert — touch only OK's own entry
+// ---------------------------------------------------------------------------
+
+type YamlUpsertOutcome =
+ | { kind: 'written' | 'overwritten' }
+ | { kind: 'declined'; reason: McpDeclineReason };
+
+/**
+ * Add or update only OK's own `mcp_servers.<serverName>` entry in a Hermes
+ * `config.yaml`, leaving the user's model + tool-filter config and sibling MCP
+ * servers in place — by editing a `yaml` Document rather than re-serializing
+ * from a plain object. Comments, keys, values, key order, and block-style
+ * formatting are preserved, along with the file's byte-level encoding (a leading
+ * BOM, CRLF endings, trailing-newline state).
+ *
+ * The one fidelity caveat: `yaml`'s AST round-trip may normalize whitespace
+ * INSIDE a flow collection (`["a","b"]` → `[ "a", "b" ]`) — cosmetic, never a
+ * value or comment change. This is the same AST-level fidelity OK already
+ * accepts for editing its OWN `config.yml` (`config/yaml-patch.ts`), so there is
+ * no byte-perfect JS alternative worth a second engine here.
+ *
+ * Unlike the TOML path there is no lossy JS fallback to guard against: the pure
+ * `yaml` package is itself comment-preserving, so every present, parseable
+ * config is safely surgically edited. A parse error (including a duplicate
+ * `mcp_servers` key, which `yaml` reports as a structural error rather than
+ * throwing) DECLINES — the file is left byte-unchanged. Absent/blank files have
+ * nothing to preserve and are created fresh.
+ */
+function upsertYamlMcpConfig(
+ configPath: string,
+ topLevelKey: string,
+ serverName: string,
+ entry: Record<string, unknown>,
+): YamlUpsertOutcome {
+ let raw = '';
+ if (existsSync(configPath)) {
+ try {
+ raw = readFileSync(configPath, 'utf-8');
+ } catch (err) {
+ // Same read-failure-vs-malformed conflation as the JSON/TOML paths; trace
+ // under OK_DEBUG_NATIVE so an EACCES/EROFS on the config isn't invisible.
+ debugNativeLoadFailure('yaml config read failed', err);
+ return { kind: 'declined', reason: 'unparseable' };
+ }
+ }
+ if (raw.trim() === '') {
+ writeYamlConfig(configPath, { [topLevelKey]: { [serverName]: entry } });
+ return { kind: 'written' };
+ }
+ // Gate on raw size before parse + edit so a pathologically large file costs
+ // only a read, not a full document build, on every launch.
+ if (Buffer.byteLength(raw, 'utf-8') > JSON_CONFIG_MAX_BYTES) {
+ return { kind: 'declined', reason: 'oversize' };
+ }
+
+ const hasBom = raw.charCodeAt(0) === 0xfeff;
+ const body = hasBom ? raw.slice(1) : raw;
+ const doc = parseDocument(body);
+ // `yaml` collects structural errors (bad indent, duplicate keys) rather than
+ // throwing; a config we can't cleanly parse is left untouched.
+ if (doc.errors.length > 0) return { kind: 'declined', reason: 'unparseable' };
+
+ const path = [topLevelKey, serverName];
+ const entryExists = doc.hasIn(path);
+ // `setIn` auto-creates a missing `mcp_servers` map, but throws if it already
+ // exists as a non-collection — an empty `mcp_servers:` parses as Scalar(null).
+ // Drop that stray scalar first so the entry can nest under a fresh map.
+ if (doc.hasIn([topLevelKey]) && !isCollection(doc.getIn([topLevelKey], true))) {
+ doc.deleteIn([topLevelKey]);
+ }
+ // Wrap the plain entry into YAML nodes explicitly so `command`/`args`/`env`
+ // serialize as a proper map/seq (the multi-line chain becomes a block scalar).
+ doc.setIn(path, doc.createNode(entry));
+
+ // `yaml` emits LF, always ends with a trailing newline, and drops a leading
+ // BOM; restore the source file's encoding so the only byte-level change is
+ // OK's own entry (mirrors the TOML path's toml_edit normalization fix-up).
+ let text = doc.toString();
+ const crlfDominant = isCrlfDominant(body);
+ const wantTrailingNewline = body.endsWith('\n');
+ if (wantTrailingNewline) {
+ if (!text.endsWith('\n')) text = `${text}\n`;
+ } else {
+ text = text.replace(/\n+$/, '');
+ }
+ if (crlfDominant) {
+ text = text.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
+ }
+ const newText = `${hasBom ? '\uFEFF' : ''}${text}`;
+
+ if (newText !== raw) {
+ atomicWriteFileSync(configPath, newText, { mode: existingFileMode(configPath) });
+ }
+ return { kind: entryExists ? 'overwritten' : 'written' };
+}
+
// ---------------------------------------------------------------------------
// Scope types + helpers
// ---------------------------------------------------------------------------
@@ -1257,9 +1367,10 @@ export function writeEditorMcpConfig(
// target's directory may differ from the symlink's, so ensure it exists.
const writePath = resolveHarnessWritePaths(configPath).writePath;
mkdirSync(dirname(writePath), { recursive: true });
- // Both formats edit only OK's own entry: TOML through the native
+ // Every format edits only OK's own entry: TOML through the native
// format-preserving addon (declining on the JS fallback rather than a
- // lossy whole-file rewrite), JSON through the surgical jsonc editor.
+ // lossy whole-file rewrite), YAML through the `yaml` document model
+ // (Hermes), JSON through the surgical jsonc editor.
if (target.format === 'toml') {
const tomlOutcome = upsertTomlMcpConfig(
getTomlConfigEngine(),
@@ -1272,6 +1383,17 @@ export function writeEditorMcpConfig(
if (tomlOutcome.kind === 'declined') captured.declineReason = tomlOutcome.reason;
return;
}
+ if (target.format === 'yaml') {
+ const yamlOutcome = upsertYamlMcpConfig(
+ writePath,
+ target.topLevelKey,
+ serverName,
+ targetEntry,
+ );
+ captured.action = yamlOutcome.kind;
+ if (yamlOutcome.kind === 'declined') captured.declineReason = yamlOutcome.reason;
+ return;
+ }
const outcome = upsertJsonMcpConfig(
writePath,
target.topLevelKey,
@@ -1678,6 +1800,17 @@ export function classifyExistingMcpEntry(
return classifyContainer(config, target.topLevelKey, serverName, target.serverMapSubKey);
}
+ // YAML (Hermes) parses through the same `yaml` document model the upsert
+ // uses — structural errors (including a duplicate `mcp_servers` key) surface
+ // as a decline rather than an arbitrary edit target, and a leading BOM is
+ // stripped so it doesn't derail the parse.
+ if (target.format === 'yaml') {
+ const doc = parseDocument(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+ if (doc.errors.length > 0) return { kind: 'decline', reason: 'unparseable' };
+ const config = (doc.toJS() ?? {}) as Record<string, unknown>;
+ return classifyContainer(config, target.topLevelKey, serverName, target.serverMapSubKey);
+ }
+
const tree = parseJsoncObjectTree(raw);
if (!tree) return { kind: 'decline', reason: 'unparseable' };
if (countTopLevelKey(tree, target.topLevelKey) > 1) {
diff --git a/packages/cli/src/commands/mcp-config-removal.ts b/packages/cli/src/commands/mcp-config-removal.ts
index e8761bfb5..be3be8737 100644
--- a/packages/cli/src/commands/mcp-config-removal.ts
+++ b/packages/cli/src/commands/mcp-config-removal.ts
@@ -13,9 +13,10 @@
* entry — never a foreign server that merely shares the `open-knowledge`
* key (a squatting entry in a shared/cloned config, or a user's own fork).
* 3. Edits the source text in place (jsonc-parser `modify` with `undefined`
- * for JSON; the native `toml_edit` `removeEntry` for TOML) so every other
- * token — sibling servers, comments, key order, indentation, a leading
- * BOM, CRLF endings, trailing-newline state — is byte-preserved.
+ * for JSON; the native `toml_edit` `removeEntry` for TOML; the `yaml`
+ * document model for YAML/Hermes) so every other token — sibling servers,
+ * comments, key order, indentation, a leading BOM, CRLF endings,
+ * trailing-newline state — is byte-preserved.
*
* TOML removal needs the format-preserving native engine (same constraint as
* the TOML upsert): on the JS fallback a present config can only be rewritten
@@ -25,6 +26,7 @@
import { readFileSync, rmSync } from 'node:fs';
import { atomicWriteFileSync } from '@inkeep/open-knowledge-core/server';
+import { parseDocument } from 'yaml';
import { isOwnPiManagedFileEntry } from '../integrations/pi-extension.ts';
import { getTomlConfigEngine } from '../native/toml-config-engine.ts';
import { type EditorMcpTarget, isEntryUpToDate, isOwnManagedEntry } from './editors.ts';
@@ -143,9 +145,9 @@ export function removeOwnMcpEntry(
return { kind: 'removed' };
}
- return target.format === 'toml'
- ? removeTomlEntry(configPath, serverName)
- : removeJsonEntry(configPath, target.topLevelKey, target.serverMapSubKey, serverName);
+ if (target.format === 'toml') return removeTomlEntry(configPath, serverName);
+ if (target.format === 'yaml') return removeYamlEntry(configPath, target.topLevelKey, serverName);
+ return removeJsonEntry(configPath, target.topLevelKey, target.serverMapSubKey, serverName);
}
function removeJsonEntry(
@@ -177,6 +179,60 @@ function removeJsonEntry(
return { kind: 'removed' };
}
+function removeYamlEntry(
+ configPath: string,
+ topLevelKey: string,
+ serverName: string,
+): McpRemoveOutcome {
+ let raw: string;
+ try {
+ raw = readFileSync(configPath, 'utf-8');
+ } catch {
+ return { kind: 'declined', reason: 'unparseable' };
+ }
+ if (Buffer.byteLength(raw, 'utf-8') > JSON_CONFIG_MAX_BYTES) {
+ return { kind: 'declined', reason: 'oversize' };
+ }
+
+ const hasBom = raw.charCodeAt(0) === 0xfeff;
+ const body = hasBom ? raw.slice(1) : raw;
+ const doc = parseDocument(body);
+ if (doc.errors.length > 0) {
+ return { kind: 'declined', reason: 'unparseable' };
+ }
+
+ const path = [topLevelKey, serverName];
+ if (!doc.hasIn(path)) {
+ // The classifier saw our entry but the document walk finds nothing to
+ // delete — treat as already-absent rather than write an identical file.
+ return { kind: 'not-present' };
+ }
+ // Delete only OK's own leaf, leaving a possibly-empty `mcp_servers` map — the
+ // same guest discipline the JSON path applies (`surgicalJsonDelete` removes
+ // the leaf, never the sibling container).
+ doc.deleteIn(path);
+
+ // `yaml` emits LF, always ends with a trailing newline, and drops a leading
+ // BOM; restore the source file's encoding so the only byte-level change is the
+ // removal of OK's own entry (mirrors the TOML path's normalization fix-up).
+ let text = doc.toString();
+ const crlfDominant = isCrlfDominant(body);
+ const wantTrailingNewline = body.trim() === '' || body.endsWith('\n');
+ if (wantTrailingNewline) {
+ if (!text.endsWith('\n')) text = `${text}\n`;
+ } else {
+ text = text.replace(/\n+$/, '');
+ }
+ if (crlfDominant) {
+ text = text.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n');
+ }
+ const newText = `${hasBom ? '\uFEFF' : ''}${text}`;
+ if (newText !== raw) {
+ atomicWriteFileSync(configPath, newText, { mode: existingFileMode(configPath) });
+ }
+ return { kind: 'removed' };
+}
+
function removeTomlEntry(configPath: string, serverName: string): McpRemoveOutcome {
const engine = getTomlConfigEngine();
if (engine.backend === 'fallback') {
diff --git a/packages/cli/src/commands/mcp-yaml-surgical-write.test.ts b/packages/cli/src/commands/mcp-yaml-surgical-write.test.ts
new file mode 100644
index 000000000..251d9b65e
--- /dev/null
+++ b/packages/cli/src/commands/mcp-yaml-surgical-write.test.ts
@@ -0,0 +1,246 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { chmodSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { CHAIN_V1, EDITOR_TARGETS, type EditorMcpTarget } from './editors.ts';
+import { writeEditorMcpConfig } from './init.ts';
+import { removeOwnMcpEntry } from './mcp-config-removal.ts';
+
+// Drive the real write spine against a temp Hermes `config.yaml`, exercising the
+// format-preserving `yaml` document path end to end through
+// `writeEditorMcpConfig`: comment/sibling preservation, the BOM/EOL/trailing-
+// newline wrapper, register-vs-update labeling, decline-on-unparseable, and the
+// reverse removal path. Hermes' whole config (models, tool filters) lives in
+// this same file, so touching only OK's own entry is load-bearing.
+
+let dir: string;
+
+function tempFile(name: string): string {
+ dir = mkdtempSync(join(tmpdir(), 'ok-yaml-surgical-'));
+ return join(dir, name);
+}
+
+// Override `detectPath` too (not just `configPath`): Hermes is
+// `offerOnlyWhenDetected`, so the availability gate probes the detect dir even
+// under `skipAvailabilityCheck`. Point it at the temp dir so the gate passes
+// deterministically instead of depending on a real `~/.hermes`.
+function hermesTargetForFile(configPath: string): EditorMcpTarget {
+ return {
+ ...EDITOR_TARGETS.hermes,
+ configPath: () => configPath,
+ detectPath: () => dirname(configPath),
+ };
+}
+
+function writeHermes(configPath: string) {
+ return writeEditorMcpConfig(hermesTargetForFile(configPath), '', {
+ mode: 'published',
+ skipAvailabilityCheck: true,
+ });
+}
+
+const PUBLISHED_CHAIN_ENTRY = { command: '/bin/sh', args: ['-l', '-c', CHAIN_V1] };
+
+describe('surgical YAML MCP write', () => {
+ afterEach(() => {
+ if (dir) rmSync(dir, { recursive: true, force: true });
+ });
+
+ it('creates a fresh config with our entry when the file is absent', () => {
+ const configPath = tempFile('config.yaml');
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('written');
+
+ const parsed = parseYaml(readFileSync(configPath, 'utf-8'));
+ expect(parsed.mcp_servers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
+ });
+
+ it('inserts only our entry, preserving comments, siblings, and key order', () => {
+ const configPath = tempFile('config.yaml');
+ const original = [
+ '# hand-written header',
+ 'model: hermes-4',
+ 'temperature: 0.7',
+ '',
+ 'mcp_servers:',
+ ' github:',
+ ' command: npx',
+ ' args: ["-y", "@modelcontextprotocol/server-github"] # keep this note',
+ '',
+ ].join('\n');
+ writeFileSync(configPath, original);
+
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('written');
+
+ const after = readFileSync(configPath, 'utf-8');
+ // Comments + block-style content survive; the sibling's inline comment is
+ // preserved too. (yaml's AST round-trip may normalize whitespace INSIDE a
+ // flow collection — `["-y","x"]` → `[ "-y", "x" ]` — but never drops the
+ // comment or changes the value; the structural parse below is the fidelity
+ // proof. This matches how OK edits its own config.yml via parseDocument.)
+ expect(after).toContain('# hand-written header');
+ expect(after).toContain('# keep this note');
+ expect(after).toContain('temperature: 0.7');
+
+ // Independent parse confirms data-equality: the sibling is untouched and our
+ // entry is added under the same `mcp_servers` map with the published chain.
+ const parsed = parseYaml(after);
+ expect(parsed.model).toBe('hermes-4');
+ expect(parsed.temperature).toBe(0.7);
+ expect(parsed.mcp_servers.github).toEqual({
+ command: 'npx',
+ args: ['-y', '@modelcontextprotocol/server-github'],
+ });
+ expect(parsed.mcp_servers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
+ });
+
+ it('creates the mcp_servers map when the file has none, keeping the prefix', () => {
+ const configPath = tempFile('config.yaml');
+ const original = '# my config\nmodel: hermes-4\n';
+ writeFileSync(configPath, original);
+
+ writeHermes(configPath);
+ const after = readFileSync(configPath, 'utf-8');
+ // Everything the user wrote survives verbatim; the new map is appended.
+ expect(after).toContain('# my config');
+ expect(after).toContain('model: hermes-4');
+ expect(parseYaml(after).mcp_servers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
+ });
+
+ it('handles an empty `mcp_servers:` scalar (null) without throwing', () => {
+ const configPath = tempFile('config.yaml');
+ // `mcp_servers:` with no body parses as Scalar(null); setIn must replace it
+ // with a map rather than throwing "Expected YAML collection".
+ writeFileSync(configPath, 'model: hermes-4\nmcp_servers:\n');
+
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('written');
+ const parsed = parseYaml(readFileSync(configPath, 'utf-8'));
+ expect(parsed.model).toBe('hermes-4');
+ expect(parsed.mcp_servers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
+ });
+
+ it('labels an existing OK entry update as overwritten', () => {
+ const configPath = tempFile('config.yaml');
+ writeFileSync(configPath, 'mcp_servers:\n open-knowledge:\n command: old\n args: []\n');
+
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('overwritten');
+ expect(parseYaml(readFileSync(configPath, 'utf-8')).mcp_servers['open-knowledge']).toEqual(
+ PUBLISHED_CHAIN_ENTRY,
+ );
+ });
+
+ it('is idempotent: a second write does not churn the file', () => {
+ const configPath = tempFile('config.yaml');
+ writeHermes(configPath);
+ const first = readFileSync(configPath, 'utf-8');
+ const result = writeHermes(configPath);
+ // Entry already present + current: labeled overwritten, bytes unchanged.
+ expect(result.action).toBe('overwritten');
+ expect(readFileSync(configPath, 'utf-8')).toBe(first);
+ });
+
+ it('preserves a leading UTF-8 BOM byte-for-byte', () => {
+ const configPath = tempFile('config.yaml');
+ // Explicit escape — never an invisible BOM literal in source.
+ const original = '\uFEFF# bom config\nmodel: hermes-4\n';
+ writeFileSync(configPath, original);
+
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('written');
+
+ const after = readFileSync(configPath, 'utf-8');
+ expect(after.charCodeAt(0)).toBe(0xfeff);
+ expect(after).toContain('# bom config');
+ expect(parseYaml(after).mcp_servers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
+ });
+
+ it('preserves CRLF line endings elsewhere', () => {
+ const configPath = tempFile('config.yaml');
+ const original = '# crlf config\r\nmodel: hermes-4\r\n';
+ writeFileSync(configPath, original);
+
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('written');
+
+ const after = readFileSync(configPath, 'utf-8');
+ // Every newline in the file is CRLF — no lone LF leaked in.
+ expect(after.replace(/\r\n/g, '')).not.toContain('\n');
+ expect(after).toContain('# crlf config');
+ expect(parseYaml(after).mcp_servers['open-knowledge']).toEqual(PUBLISHED_CHAIN_ENTRY);
+ });
+
+ it.skipIf(process.platform === 'win32')(
+ 'preserves a user-tightened file mode (0600) on an in-place rewrite',
+ () => {
+ const configPath = tempFile('config.yaml');
+ writeFileSync(configPath, '# my hermes config\nmodel: hermes-4\n');
+ // A tightened Hermes config (it can carry provider tokens under
+ // `mcp_servers.*.env`) must not be widened when OK adds its entry.
+ chmodSync(configPath, 0o600);
+
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('written');
+ expect(statSync(configPath).mode & 0o777).toBe(0o600);
+ },
+ );
+
+ it('declines a present, unparseable config (left byte-unchanged)', () => {
+ const configPath = tempFile('config.yaml');
+ // Bad indentation / structure the yaml parser reports as an error.
+ const original = 'model: hermes-4\n bad: : : indent\n\t- mixed\n';
+ writeFileSync(configPath, original);
+
+ const result = writeHermes(configPath);
+ expect(result.action).toBe('declined');
+ // The file OK couldn't safely parse is left exactly as it was.
+ expect(readFileSync(configPath, 'utf-8')).toBe(original);
+ });
+
+ it('removes only our own entry, preserving the sibling server', () => {
+ const configPath = tempFile('config.yaml');
+ const original = [
+ '# hand-written header',
+ 'model: hermes-4',
+ 'mcp_servers:',
+ ' github:',
+ ' command: npx',
+ ' args: ["-y", "@modelcontextprotocol/server-github"]',
+ '',
+ ].join('\n');
+ writeFileSync(configPath, original);
+ writeHermes(configPath);
+
+ const outcome = removeOwnMcpEntry(hermesTargetForFile(configPath), '', undefined, configPath);
+ expect(outcome.kind).toBe('removed');
+
+ const parsed = parseYaml(readFileSync(configPath, 'utf-8'));
+ // OK's entry is gone; the user's sibling + comment survive.
+ expect(parsed.mcp_servers['open-knowledge']).toBeUndefined();
+ expect(parsed.mcp_servers.github).toEqual({
+ command: 'npx',
+ args: ['-y', '@modelcontextprotocol/server-github'],
+ });
+ expect(readFileSync(configPath, 'utf-8')).toContain('# hand-written header');
+ });
+
+ it('leaves a foreign server sharing our key untouched on removal', () => {
+ const configPath = tempFile('config.yaml');
+ // A server squatting on the `open-knowledge` name that is NOT OK's managed
+ // chain shape must be preserved, never deleted.
+ writeFileSync(
+ configPath,
+ 'mcp_servers:\n open-knowledge:\n command: not-ok\n args: [evil]\n',
+ );
+
+ const outcome = removeOwnMcpEntry(hermesTargetForFile(configPath), '', undefined, configPath);
+ expect(outcome.kind).toBe('left-foreign');
+ expect(parseYaml(readFileSync(configPath, 'utf-8')).mcp_servers['open-knowledge']).toEqual({
+ command: 'not-ok',
+ args: ['evil'],
+ });
+ });
+});
diff --git a/packages/core/src/constants/editors.ts b/packages/core/src/constants/editors.ts
index 765376518..71104c0fa 100644
--- a/packages/core/src/constants/editors.ts
+++ b/packages/core/src/constants/editors.ts
@@ -15,7 +15,8 @@ export type EditorId =
| 'openclaw'
| 'pi'
| 'antigravity'
- | 'lm-studio';
+ | 'lm-studio'
+ | 'hermes';
export const ALL_EDITOR_IDS = [
'claude',
@@ -27,6 +28,7 @@ export const ALL_EDITOR_IDS = [
'pi',
'antigravity',
'lm-studio',
+ 'hermes',
] as const satisfies readonly EditorId[];
/**
@@ -45,6 +47,7 @@ export const EDITOR_LABELS = {
pi: 'Pi',
antigravity: 'Antigravity',
'lm-studio': 'LM Studio',
+ hermes: 'Hermes',
} as const satisfies Record<EditorId, string>;
/**
@@ -109,6 +112,10 @@ export const EDITOR_PROJECT_SKILL_ROOT = {
// LM Studio is an MCP host (its chat connects to MCP servers) with no Agent
// Skills surface at all — OK's only integration is the user-global MCP config.
'lm-studio': null,
+ // Hermes Agent (Nous Research) is a user-global terminal agent: its whole
+ // config lives at `~/.hermes/config.yaml` with no project-scoped skill dir OK
+ // writes — same null-project-skill posture as OpenClaw / Claude Desktop.
+ hermes: null,
} as const satisfies Record<EditorId, string | null>;
/** Editor ids that have a project skill surface (valid install-projection targets). */
@@ -158,6 +165,7 @@ export const EDITOR_SETUP_DOC_SLUG = {
pi: 'pi',
antigravity: 'antigravity',
'lm-studio': 'lm-studio',
+ hermes: 'hermes',
} as const satisfies Record<EditorId, string>;
/**
@@ -194,4 +202,8 @@ export const EDITOR_PROJECT_CONFIG_PATH = {
// Cursor's notation but has no project-local variant), so it is never
// detected as "project-configured".
'lm-studio': null,
+ // Hermes' MCP config is user-global (`~/.hermes/config.yaml`, servers under
+ // `mcp_servers`); no project-local variant, so it is never detected as
+ // "project-configured" — same as OpenClaw.
+ hermes: null,
} as const satisfies Record<EditorId, string | null>;
diff --git a/packages/core/src/skill-targets/schema.ts b/packages/core/src/skill-targets/schema.ts
index 9f76f46b8..23ccc467c 100644
--- a/packages/core/src/skill-targets/schema.ts
+++ b/packages/core/src/skill-targets/schema.ts
@@ -36,14 +36,17 @@ export const SKILL_TARGETS_SCHEMA_VERSION = 1;
* single source `PROJECT_SKILL_EDITOR_IDS` (derived from `EDITOR_PROJECT_SKILL_ROOT`)
* so the two can't drift. z.enum needs a literal tuple, which the derived array's
* `.filter` widens to `EditorId`, so the cast restates the narrow literal shape:
- * `Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'antigravity'>` is exactly
- * the set of editors WITH a project skill surface (`claude` / `cursor` /
- * `codex` / `opencode` / `pi`). claude-desktop, openclaw, and antigravity have
- * a null project skill root (user-global skills only), so they are excluded.
- * schema.test.ts asserts the cast stays value-equal to the derived list as a
- * backstop.
+ * `Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'antigravity' | 'hermes'>`
+ * is exactly the set of editors WITH a project skill surface (`claude` /
+ * `cursor` / `codex` / `opencode` / `pi`). claude-desktop, openclaw,
+ * antigravity, and hermes have a null project skill root (user-global skills
+ * only), so they are excluded. schema.test.ts asserts the cast stays
+ * value-equal to the derived list as a backstop.
*/
-type ProjectSkillEditorId = Exclude<EditorId, 'claude-desktop' | 'openclaw' | 'antigravity'>;
+type ProjectSkillEditorId = Exclude<
+ EditorId,
+ 'claude-desktop' | 'openclaw' | 'antigravity' | 'lm-studio' | 'hermes'
+>;
export const SkillTargetEditorSchema = z.enum(
// Double cast (through `unknown`): the derived array is typed `EditorId[]`,
// which TS won't directly narrow to the literal tuple z.enum needs. Runtime
diff --git a/packages/desktop/tests/integration/m1-smoke.test.ts b/packages/desktop/tests/integration/m1-smoke.test.ts
index cb8e2ab4d..e32beec65 100644
--- a/packages/desktop/tests/integration/m1-smoke.test.ts
+++ b/packages/desktop/tests/integration/m1-smoke.test.ts
@@ -401,7 +401,7 @@ describe('M1 smoke', () => {
typeName: 'EditorId',
canonicalPath: editorsConstantPath,
canonicalRe: /type\s+EditorId\s*=([^;]+);/,
- expectedLiteralCount: 9,
+ expectedLiteralCount: 10,
inlineRe:
/'claude'\s*\|\s*'claude-desktop'\s*\|\s*'cursor'\s*\|\s*'codex'\s*\|\s*'opencode'\s*\|\s*'openclaw'/,
mirrors: [