agenticros 0.3.1 → 0.3.3

package/dist/util/hermes-config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Read/write helpers for Hermes Agent MCP config (`~/.hermes/config.yaml`).
+ *
+ * Hermes stores MCP servers under `mcp_servers.<name>` in YAML. We only
+ * manage the `agenticros` entry — other servers are preserved.
+ */
+export interface HermesAgenticrosConfig {
+    configPath: string;
+    exists: boolean;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    connectTimeout?: number;
+    timeout?: number;
+    enabled?: boolean;
+}
+export interface HermesConfigIssue {
+    severity: "red" | "yellow";
+    message: string;
+    hint?: string;
+}
+export interface HermesConfigValidation {
+    ok: boolean;
+    issues: HermesConfigIssue[];
+}
+/** Global Hermes config: `~/.hermes/config.yaml`. */
+export declare function globalHermesConfigPath(): string;
+/**
+ * Build the YAML block for the AgenticROS MCP server. Uses an absolute path
+ * to index.js (required by Hermes stdio transport) and leaves namespace empty
+ * so `~/.agenticros/config.json` / `agenticros mode` drives the active robot.
+ */
+export declare function buildAgenticrosMcpYamlBlock(mcpEntryAbs: string, namespace?: string): string;
+/** Insert or replace the agenticros MCP block, preserving other YAML content. */
+export declare function upsertAgenticrosBlock(existingContent: string | null, block: string): string;
+/** Parse the agenticros MCP section from a Hermes config.yaml file. */
+export declare function readHermesAgenticrosConfig(configPath: string): HermesAgenticrosConfig;
+export declare function writeHermesAgenticrosConfig(configPath: string, mcpEntryAbs: string, options?: {
+    namespace?: string;
+}): void;
+/** Validate Hermes agenticros MCP config against expected MCP binary path. */
+export declare function validateHermesAgenticrosConfig(cfg: HermesAgenticrosConfig, mcpEntryExpected?: string): HermesConfigValidation;
+/** Doctor check entries for Hermes MCP config (used by `agenticros doctor`). */
+export declare function buildHermesDoctorChecks(mcpEntryExpected: string | undefined): Array<{
+    id: string;
+    label: string;
+    severity: "green" | "yellow" | "red";
+    hint?: string;
+    detail?: string;
+}>;
+//# sourceMappingURL=hermes-config.d.ts.map

package/dist/util/hermes-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermes-config.d.ts","sourceRoot":"","sources":["../../src/util/hermes-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B;AAKD,qDAAqD;AACrD,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CAYvF;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CA+B3F;AAED,uEAAuE;AACvE,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,CA4BrF;AAED,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,IAAI,CAON;AAED,8EAA8E;AAC9E,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,sBAAsB,EAC3B,gBAAgB,CAAC,EAAE,MAAM,GACxB,sBAAsB,CAyExB;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,MAAM,GAAG,SAAS,GACnC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyC5G"}

package/dist/util/hermes-config.js

@@ -0,0 +1,277 @@
+/**
+ * Read/write helpers for Hermes Agent MCP config (`~/.hermes/config.yaml`).
+ *
+ * Hermes stores MCP servers under `mcp_servers.<name>` in YAML. We only
+ * manage the `agenticros` entry — other servers are preserved.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+const MCP_SERVERS_KEY = "mcp_servers:";
+const AGENTICROS_KEY = "agenticros:";
+/** Global Hermes config: `~/.hermes/config.yaml`. */
+export function globalHermesConfigPath() {
+    return join(homedir(), ".hermes", "config.yaml");
+}
+/**
+ * Build the YAML block for the AgenticROS MCP server. Uses an absolute path
+ * to index.js (required by Hermes stdio transport) and leaves namespace empty
+ * so `~/.agenticros/config.json` / `agenticros mode` drives the active robot.
+ */
+export function buildAgenticrosMcpYamlBlock(mcpEntryAbs, namespace = "") {
+    const escaped = mcpEntryAbs.replace(/\\/g, "\\\\");
+    const nsYaml = namespace.replace(/"/g, '\\"');
+    return `${MCP_SERVERS_KEY}
+  ${AGENTICROS_KEY}
+    command: "node"
+    args: ["${escaped}"]
+    env:
+      AGENTICROS_ROBOT_NAMESPACE: "${nsYaml}"
+    connect_timeout: 60
+    timeout: 120
+`;
+}
+/** Insert or replace the agenticros MCP block, preserving other YAML content. */
+export function upsertAgenticrosBlock(existingContent, block) {
+    const trimmedBlock = block.trimEnd() + "\n";
+    if (!existingContent?.trim()) {
+        return trimmedBlock;
+    }
+    const lines = existingContent.split("\n");
+    const mcpIdx = lines.findIndex((l) => l.trim() === MCP_SERVERS_KEY);
+    if (mcpIdx < 0) {
+        const sep = lines.length > 0 && lines[lines.length - 1]?.trim() !== "" ? "\n" : "";
+        return lines.join("\n") + sep + trimmedBlock;
+    }
+    const agentIdx = findAgenticrosLineIndex(lines, mcpIdx);
+    if (agentIdx < 0) {
+        const insertAt = findMcpServersInsertPoint(lines, mcpIdx);
+        const agentLines = trimmedBlock
+            .split("\n")
+            .slice(1)
+            .filter((l) => l.trim().length > 0);
+        const out = [...lines.slice(0, insertAt), ...agentLines, ...lines.slice(insertAt)];
+        return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+    }
+    const endIdx = findAgenticrosEndIndex(lines, agentIdx);
+    const agentLines = trimmedBlock
+        .split("\n")
+        .slice(1)
+        .filter((l) => l.startsWith("  "));
+    const out = [...lines.slice(0, agentIdx), ...agentLines, ...lines.slice(endIdx)];
+    return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+/** Parse the agenticros MCP section from a Hermes config.yaml file. */
+export function readHermesAgenticrosConfig(configPath) {
+    const base = { configPath, exists: existsSync(configPath) };
+    if (!base.exists)
+        return base;
+    let content;
+    try {
+        content = readFileSync(configPath, "utf8");
+    }
+    catch {
+        return base;
+    }
+    const lines = content.split("\n");
+    const mcpIdx = lines.findIndex((l) => l.trim() === MCP_SERVERS_KEY);
+    if (mcpIdx < 0)
+        return base;
+    const agentIdx = findAgenticrosLineIndex(lines, mcpIdx);
+    if (agentIdx < 0)
+        return base;
+    const endIdx = findAgenticrosEndIndex(lines, agentIdx);
+    const section = lines.slice(agentIdx, endIdx).join("\n");
+    base.command = parseYamlString(section, "command");
+    base.args = parseYamlStringArray(section, "args");
+    base.env = parseYamlEnvBlock(section);
+    base.connectTimeout = parseYamlNumber(section, "connect_timeout");
+    base.timeout = parseYamlNumber(section, "timeout");
+    base.enabled = parseYamlBoolean(section, "enabled");
+    return base;
+}
+export function writeHermesAgenticrosConfig(configPath, mcpEntryAbs, options) {
+    const abs = resolve(mcpEntryAbs);
+    const block = buildAgenticrosMcpYamlBlock(abs, options?.namespace ?? "");
+    const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : null;
+    const merged = upsertAgenticrosBlock(existing, block);
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, merged, "utf8");
+}
+/** Validate Hermes agenticros MCP config against expected MCP binary path. */
+export function validateHermesAgenticrosConfig(cfg, mcpEntryExpected) {
+    const issues = [];
+    if (!cfg.exists) {
+        issues.push({
+            severity: "yellow",
+            message: `Hermes config missing (${cfg.configPath})`,
+            hint: "Run `agenticros hermes setup` to register the AgenticROS MCP server.",
+        });
+        return { ok: false, issues };
+    }
+    if (!cfg.command && (!cfg.args || cfg.args.length === 0)) {
+        issues.push({
+            severity: "red",
+            message: "Hermes mcp_servers.agenticros has no command or args",
+            hint: "Run `agenticros hermes setup` to repair the entry.",
+        });
+    }
+    const mcpPath = cfg.args?.[0];
+    if (mcpPath && !isAbsolute(mcpPath)) {
+        issues.push({
+            severity: "red",
+            message: "Hermes MCP path is relative — Hermes cwd is not the repo root",
+            hint: "Run `agenticros hermes setup` to rewrite with an absolute path.",
+        });
+    }
+    if (mcpEntryExpected && mcpPath) {
+        const expected = resolve(mcpEntryExpected);
+        const actual = resolve(mcpPath);
+        if (actual !== expected && !existsSync(actual)) {
+            issues.push({
+                severity: "red",
+                message: "Hermes MCP path does not point to a built server",
+                hint: `Expected ${expected}. Run \`agenticros hermes setup\`.`,
+            });
+        }
+        else if (actual !== expected) {
+            issues.push({
+                severity: "yellow",
+                message: "Hermes MCP path differs from the CLI-resolved MCP entry",
+                hint: `CLI expects ${expected}. Run \`agenticros hermes setup\` to sync.`,
+            });
+        }
+    }
+    else if (mcpEntryExpected && !mcpPath) {
+        issues.push({
+            severity: "yellow",
+            message: "Could not parse MCP server path from Hermes config",
+            hint: "Run `agenticros hermes setup` to rewrite the entry.",
+        });
+    }
+    const ns = (cfg.env?.["AGENTICROS_ROBOT_NAMESPACE"] ?? "").trim();
+    if (ns.length > 0) {
+        issues.push({
+            severity: "yellow",
+            message: `Hermes AGENTICROS_ROBOT_NAMESPACE is hardcoded ('${ns}')`,
+            hint: 'Leave it empty in ~/.hermes/config.yaml so `agenticros mode real|sim` drives the namespace (same as Codex).',
+        });
+    }
+    if (cfg.enabled === false) {
+        issues.push({
+            severity: "yellow",
+            message: "Hermes agenticros MCP server is disabled (enabled: false)",
+            hint: "Remove enabled: false or re-run `agenticros hermes setup`.",
+        });
+    }
+    const hasRed = issues.some((i) => i.severity === "red");
+    return { ok: !hasRed && issues.length === 0, issues };
+}
+/** Doctor check entries for Hermes MCP config (used by `agenticros doctor`). */
+export function buildHermesDoctorChecks(mcpEntryExpected) {
+    const checks = [];
+    const configPath = globalHermesConfigPath();
+    const cfg = readHermesAgenticrosConfig(configPath);
+    if (!cfg.exists) {
+        checks.push({
+            id: "hermes-config",
+            label: "Hermes MCP config missing (~/.hermes/config.yaml)",
+            severity: "yellow",
+            hint: "Run `agenticros hermes setup` to register the AgenticROS MCP server.",
+        });
+        return checks;
+    }
+    const v = validateHermesAgenticrosConfig(cfg, mcpEntryExpected);
+    if (v.ok) {
+        checks.push({
+            id: "hermes-config",
+            label: "Hermes MCP config OK",
+            severity: "green",
+            detail: configPath,
+        });
+    }
+    else {
+        const worst = v.issues.some((i) => i.severity === "red") ? "red" : "yellow";
+        const first = v.issues[0];
+        checks.push({
+            id: "hermes-config",
+            label: `Hermes MCP: ${first.message}`,
+            severity: worst,
+            hint: first.hint ?? "Run `agenticros hermes setup`.",
+        });
+    }
+    return checks;
+}
+function findAgenticrosLineIndex(lines, mcpIdx) {
+    for (let i = mcpIdx + 1; i < lines.length; i++) {
+        const trimmed = lines[i]?.trim() ?? "";
+        if (/^\S/.test(lines[i] ?? "") && trimmed !== MCP_SERVERS_KEY)
+            break;
+        if (trimmed === AGENTICROS_KEY)
+            return i;
+    }
+    return -1;
+}
+function findMcpServersInsertPoint(lines, mcpIdx) {
+    let insertAt = mcpIdx + 1;
+    for (let i = mcpIdx + 1; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (/^\S/.test(line) && line.trim() !== MCP_SERVERS_KEY)
+            break;
+        if (/^  \S/.test(line))
+            insertAt = i + 1;
+    }
+    return insertAt;
+}
+function findAgenticrosEndIndex(lines, agentIdx) {
+    for (let i = agentIdx + 1; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (/^  \S/.test(line) && !line.startsWith("    ") && line.trim() !== AGENTICROS_KEY) {
+            return i;
+        }
+        if (/^\S/.test(line))
+            return i;
+    }
+    return lines.length;
+}
+function parseYamlString(section, key) {
+    const re = new RegExp(`^\\s*${key}:\\s*"([^"]*)"`, "m");
+    const m = section.match(re);
+    return m?.[1];
+}
+function parseYamlBoolean(section, key) {
+    const re = new RegExp(`^\\s*${key}:\\s*(true|false)`, "m");
+    const m = section.match(re);
+    if (!m)
+        return undefined;
+    return m[1] === "true";
+}
+function parseYamlNumber(section, key) {
+    const re = new RegExp(`^\\s*${key}:\\s*(\\d+)`, "m");
+    const m = section.match(re);
+    if (!m)
+        return undefined;
+    return Number(m[1]);
+}
+function parseYamlStringArray(section, key) {
+    const inline = section.match(new RegExp(`^\\s*${key}:\\s*\\[([^\\]]*)\\]`, "m"));
+    if (inline?.[1]) {
+        return [...inline[1].matchAll(/"((?:\\.|[^"\\])*)"/g)].map((m) => m[1].replace(/\\"/g, '"').replace(/\\\\/g, "\\"));
+    }
+    return undefined;
+}
+function parseYamlEnvBlock(section) {
+    const env = {};
+    const envMatch = section.match(/^(\s*)env:\s*$/m);
+    if (!envMatch)
+        return env;
+    const baseIndent = envMatch[1]?.length ?? 0;
+    const envKeyIndent = baseIndent + 2;
+    for (const line of section.split("\n")) {
+        const m = line.match(new RegExp(`^\\s{${envKeyIndent}}([A-Z0-9_]+):\\s*"([^"]*)"`));
+        if (m)
+            env[m[1]] = m[2];
+    }
+    return env;
+}
+//# sourceMappingURL=hermes-config.js.map

package/dist/util/hermes-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermes-config.js","sourceRoot":"","sources":["../../src/util/hermes-config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticros",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "AgenticROS - agentic AI for ROS-powered robots. Single CLI to launch real-robot or simulated demos, manage configuration, and inspect status.",
   "keywords": [
@@ -11,6 +11,7 @@
     "agent",
     "claude",
     "codex",
+    "hermes",
     "openai",
     "openclaw",
     "gazebo",

package/runtime/BUNDLE.json

@@ -1,5 +1,5 @@
 {
-  "packedAt": "2026-06-30T23:41:17.957Z",
+  "packedAt": "2026-07-04T16:56:29.644Z",
   "repo": "https://github.com/PlaiPin/agenticros",
   "note": "This directory is a snapshot of the agenticros monorepo source. `agenticros init` will copy it to ~/agenticros and run pnpm install + colcon build there.",
   "layout": {

package/runtime/README.md

@@ -28,6 +28,7 @@ With AgenticROS, your robot can describe what it sees, follow intent ("go check
 - **[NVIDIA NemoClaw](https://github.com/NVIDIA/NemoClaw)** — Run AgenticROS inside NemoClaw's OpenShell sandbox with policy-enforced egress and managed NVIDIA inference; ROS 2, RealSense, and rosbridge stay on the host while the plugin runs sandboxed.
 - **[Anthropic Claude](https://www.anthropic.com/claude)** — A single MCP server powers **Claude Code** (terminal), **Claude Desktop** (macOS / Windows), and **Claude Dispatch** (iOS, paired to your Mac). Ask Claude what your robot sees, and it answers with a live camera snapshot and depth reading.
 - **[OpenAI Codex CLI](https://developers.openai.com/codex/)** — Same MCP server as Claude Code. One command registers Codex: `agenticros codex setup` (writes `~/.codex/config.toml` with an absolute path to the MCP binary). Full tool surface: missions, follow-me, find-object, memory. Setup guide: [docs/codex-setup.md](docs/codex-setup.md).
+- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — Model-agnostic agent gateway (OpenRouter, Ollama, 200+ providers) with MCP client support. Same MCP server as Codex: `agenticros hermes setup` writes `~/.hermes/config.yaml`. Setup guide: [docs/hermes-setup.md](docs/hermes-setup.md).
 - **[Google Gemini](https://ai.google.dev/)** — Standalone CLI that uses Gemini function calling against the same ROS 2 tools (no MCP required) — ideal for scripting and headless agents.
 
 AgenticROS is built so that new adapters (LangGraph, OpenAI, local models, voice stacks, etc.) can be added without touching the ROS 2 layer. The core transport and tool contract are platform-agnostic; adapters are thin shims that surface those tools to each agent runtime.
@@ -38,13 +39,14 @@ AgenticROS is built so that new adapters (LangGraph, OpenAI, local models, voice
 
 - **Core** (`packages/core`): Platform-agnostic ROS2 transport (rosbridge, Zenoh, local, WebRTC), config schema, and shared types. No dependency on any specific AI platform.
 - **Adapters** (`packages/agenticros`, and later others): Implement the contract for each AI platform. The OpenClaw adapter registers tools, commands, and HTTP routes with the OpenClaw gateway and uses the core for all ROS2 communication.
-- `**packages/agenticros-claude-code`** — MCP server for **Claude Code**, **Claude desktop**, **Dispatch**, and **OpenAI Codex CLI**. See [packages/agenticros-claude-code/README.md](packages/agenticros-claude-code/README.md) and [docs/codex-setup.md](docs/codex-setup.md).
+- `**packages/agenticros-claude-code`** — MCP server for **Claude Code**, **Claude desktop**, **Dispatch**, **OpenAI Codex CLI**, and **Hermes Agent**. See [packages/agenticros-claude-code/README.md](packages/agenticros-claude-code/README.md), [docs/codex-setup.md](docs/codex-setup.md), and [docs/hermes-setup.md](docs/hermes-setup.md).
 - `**packages/agenticros-gemini`** — **Gemini CLI**: use Google Gemini to chat with your robot from the terminal (same ROS2 tools, no MCP). See [packages/agenticros-gemini/README.md](packages/agenticros-gemini/README.md).
 
 ```
 User (messaging app) → OpenClaw Gateway → AgenticROS OpenClaw plugin → Core → ROS2 robots
 Claude (Code / desktop / Dispatch) → agenticros MCP server → Core → ROS2 robots (Zenoh/rosbridge)
 Codex CLI → agenticros MCP server → Core → ROS2 robots (Zenoh/rosbridge)
+Hermes Agent → agenticros MCP server → Core → ROS2 robots (Zenoh/rosbridge)
 Gemini CLI → @agenticros/gemini (function calling) → Core → ROS2 robots
 ```
 
@@ -136,7 +138,7 @@ The first run launches the interactive menu:
 ? What would you like to do?
   Launch with real robot
 ❯ Launch with simulation
-  First-time setup (workspace + OpenClaw plugin + API key)
+  First-time setup (workspace + OpenClaw plugin + Codex MCP + API key)
   Manage skills (2 registered, 0 available, 0 broken)
   Stop everything
   Doctor (health check)
@@ -144,7 +146,7 @@ The first run launches the interactive menu:
   Tail logs
 ```
 
-Pick **First-time setup** once (workspace + OpenClaw plugin + API key, all
+Pick **First-time setup** once (workspace + OpenClaw plugin + optional Codex MCP + API key, all
 idempotent), then choose how you want to run:
 
 | You want to … | Pick |
@@ -154,14 +156,18 @@ idempotent), then choose how you want to run:
 | Demo a **simulated 6-DOF arm** (UR5e-shaped, per-joint position control) | **Launch with simulation → 6-DOF arm** |
 
 Once a stack is up, point any of the supported agents — OpenClaw, Claude Code,
-Claude Desktop / Dispatch, or Gemini CLI — at the same robot and start talking
+OpenAI Codex, Hermes Agent, Claude Desktop / Dispatch, or Gemini CLI — at the same robot and start talking
 to it. The CLI tracks what it spawned (pidfiles + logs under `/tmp/agenticros-*`),
 so **Stop everything** cleanly tears the demo down.
 
 Prefer scripted invocations? Every menu item maps to a direct command:
 
 ```bash
-npx agenticros init             # one-time workspace + plugin + API key
+npx agenticros init             # one-time workspace + plugin + Codex/Hermes MCP + API key
+agenticros codex setup          # register AgenticROS MCP for OpenAI Codex CLI
+agenticros codex doctor         # validate ~/.codex/config.toml
+agenticros hermes setup         # register AgenticROS MCP for Hermes Agent
+agenticros hermes doctor        # validate ~/.hermes/config.yaml
 agenticros up real              # real robot stack
 agenticros up sim-amr           # simulated AMR (Gazebo + RViz, headless on Jetson)
 agenticros up sim-arm           # simulated 6-DOF arm
@@ -296,15 +302,15 @@ Full walkthrough, troubleshooting, and a "full-embed" alternative (ROS / RealSen
 
 ## Claude + AgenticROS (MCP)
 
-The same **AgenticROS MCP server** (`@agenticros/claude-code`) can drive the robot from **Claude Code** (terminal) or from the **Claude desktop app** on macOS (including **Claude Dispatch** on iPhone when paired to Claude on your Mac). Both use MCP; they use **different config files**.
+The **AgenticROS MCP server** (`@agenticros/claude-code`) drives the robot from **Claude Code** (terminal) or from the **Claude desktop app** on macOS (including **Claude Dispatch** on iPhone when paired to Claude on your Mac). **OpenAI Codex CLI** uses the same server — see **[Codex + AgenticROS](#codex--agenticros-mcp)** below. Claude clients use **different config files** than Codex (`.mcp.json` / `claude_desktop_config.json` vs `.codex/config.toml`).
 
-Shared setup:
+Shared MCP setup (Claude and Codex):
 
 1. **Build** (from repo root): `pnpm install && pnpm build`
 2. **AgenticROS config**: `~/.agenticros/config.json` — set `zenoh.routerEndpoint`, `robot.namespace`, `robot.cameraTopic`, etc. (see [packages/agenticros-claude-code/README.md](packages/agenticros-claude-code/README.md)).
 3. **Zenoh**: Run `zenohd` with the remote-api plugin (e.g. port 10000) — see `scripts/zenohd-agenticros.json5` or [docs/zenoh-agenticros.md](docs/zenoh-agenticros.md).
 
-Optional: override `robot.namespace` per MCP launch with env `**AGENTICROS_ROBOT_NAMESPACE`** (must match the robot’s topic namespace exactly; many setups use **no dashes** in the UUID segment).
+Optional: override `robot.namespace` per MCP launch with env `**AGENTICROS_ROBOT_NAMESPACE`**. Prefer leaving it empty in MCP/Codex config so `agenticros mode real|sim` drives the active profile (see [docs/codex-setup.md](docs/codex-setup.md)).
 
 ### Claude Code CLI (terminal)
 
@@ -347,6 +353,77 @@ Example `mcpServers` entry (adjust the path and namespace to your machine):
 
 Full steps, permissions (`mcp__agenticros`), and troubleshooting are in **[packages/agenticros-claude-code/README.md](packages/agenticros-claude-code/README.md)**.
 
+## Codex + AgenticROS (MCP)
+
+**OpenAI Codex CLI** is a standard MCP client — it uses the same `@agenticros/claude-code` server as Claude Code (missions, follow-me, find-object, memory, full ROS tool surface). No separate adapter package.
+
+### Quick setup
+
+```bash
+pnpm install && pnpm build          # or: npx agenticros init
+agenticros codex setup              # ~/.codex/config.toml (global)
+agenticros codex setup --project    # .codex/config.toml in repo root
+agenticros codex doctor             # validate absolute MCP path + namespace policy
+```
+
+Start Codex in your project directory, run `/mcp` — you should see **agenticros** connected with the full tool list. Then ask e.g. “List ROS2 topics” or “What do you see?”
+
+### Config files
+
+| File | Scope |
+|------|--------|
+| `~/.codex/config.toml` | Global — all Codex sessions |
+| `<project>/.codex/config.toml` | Project — when Codex runs in that directory |
+
+`agenticros codex setup` writes an **absolute path** to `packages/agenticros-claude-code/dist/index.js` (or the bundled MCP path after `npx agenticros init`). Relative paths fail because Codex does not spawn MCP servers from the repo root.
+
+Leave `AGENTICROS_ROBOT_NAMESPACE = ""` in the Codex env block so `~/.agenticros/config.json` and `agenticros mode real|sim` drive the active robot (same policy as `.mcp.json`).
+
+### Manual registration
+
+```bash
+codex mcp add agenticros -- node "$(pwd)/packages/agenticros-claude-code/dist/index.js"
+```
+
+Use an absolute path if not run from the repo root.
+
+### Troubleshooting
+
+- **`/mcp` does not list agenticros** → run `agenticros codex setup`; check `agenticros codex doctor`
+- **Transport timeout** → bring up Zenoh/rosbridge or run `agenticros up sim-amr` / `agenticros up real`
+- **Logs** → `/tmp/agenticros-mcp.log`
+
+Full guide: **[docs/codex-setup.md](docs/codex-setup.md)**.
+
+## Hermes + AgenticROS (MCP)
+
+**[Hermes Agent](https://github.com/NousResearch/hermes-agent)** is a model-agnostic MCP client — it uses the same `@agenticros/claude-code` server as Claude Code and Codex (missions, follow-me, find-object, memory, full ROS tool surface). No separate adapter package. Works with OpenRouter, Ollama, Anthropic, OpenAI, and 200+ other providers.
+
+### Quick setup
+
+```bash
+pnpm install && pnpm build          # or: npx agenticros init
+agenticros hermes setup             # ~/.hermes/config.yaml
+agenticros hermes doctor            # validate absolute MCP path + namespace policy
+```
+
+In Hermes, run `/reload-mcp` or restart, then `hermes mcp test agenticros`. Ask e.g. “List ROS2 topics” or “What do you see?”
+
+### Config file
+
+| File | Scope |
+|------|--------|
+| `~/.hermes/config.yaml` | Global — default Hermes profile |
+
+`agenticros hermes setup` writes an **absolute path** to the MCP server and leaves `AGENTICROS_ROBOT_NAMESPACE: ""` so `agenticros mode real|sim` drives the active robot (same policy as Codex).
+
+### Troubleshooting
+
+- **MCP tools missing** → run `agenticros hermes setup`; `/reload-mcp` in Hermes; check `agenticros hermes doctor`
+- **Transport timeout** → bring up Zenoh/rosbridge or run `agenticros up sim-amr` / `agenticros up real`
+
+Full guide: **[docs/hermes-setup.md](docs/hermes-setup.md)**.
+
 ## Gemini CLI
 
 Use **Google Gemini** to chat with your robot from the terminal (same ROS2 tools as Claude Code, no MCP).
@@ -362,7 +439,7 @@ See **[packages/agenticros-gemini/README.md](packages/agenticros-gemini/README.m
 
 ## Memory (optional)
 
-AgenticROS can give every adapter a **shared, persistent, cross-process** long-term memory so facts you teach the robot from one agent are immediately available in the others — Claude Desktop, Claude Code, Gemini CLI, OpenClaw chat. Off by default. Two backends:
+AgenticROS can give every adapter a **shared, persistent, cross-process** long-term memory so facts you teach the robot from one agent are immediately available in the others — Claude Desktop, Claude Code, OpenAI Codex, Hermes Agent, Gemini CLI, OpenClaw chat. Off by default. Two backends:
 
 - **`local`** — zero deps, JSON-on-disk at `~/.agenticros/memory.json`, keyword + recency search. Enable with one config flag.
 - **`mem0`** — semantic search via the pure-Node [`mem0ai`](https://www.npmjs.com/package/mem0ai) package (`pnpm add mem0ai`); file-backed vector store at `~/.mem0/vector_store.db` (shared across all processes on the host, no server to run); embedder auto-detects Ollama (`http://localhost:11434`) → `OPENAI_API_KEY` → clear error.
@@ -378,7 +455,7 @@ pnpm add mem0ai
 ollama pull nomic-embed-text   # ~270 MB embedder model
 ```
 
-Add `{ "memory": { "enabled": true, "backend": "mem0" } }` to `~/.agenticros/config.json` (or the OpenClaw config UI). Restart the gateway / MCP client. Then ask Claude Desktop *"remember that I have a RealSense D435i for eyes"* and ask OpenClaw *"what do I have for eyes?"* — same fact, both agents.
+Add `{ "memory": { "enabled": true, "backend": "mem0" } }` to `~/.agenticros/config.json` (or the OpenClaw config UI). Restart the gateway / MCP client. Then ask Claude Desktop *"remember that I have a RealSense D435i for eyes"* and ask Codex or OpenClaw *"what do I have for eyes?"* — same fact, every agent.
 
 ## Skills
 

package/runtime/docs/cli.md

@@ -65,7 +65,9 @@ skipped (with a checkmark) when already done:
 4. OpenClaw plugin install (via `scripts/setup_gateway_plugin.sh`)
 5. Robot config (writes `~/.agenticros/config.json`)
 6. OpenAI API key (paste once → `scripts/configure_agenticros.sh`)
-7. Final `agenticros doctor` summary
+7. Codex MCP config (optional — `agenticros codex setup` for `~/.codex/config.toml` and project `.codex/config.toml`)
+8. Hermes MCP config (optional — `agenticros hermes setup` for `~/.hermes/config.yaml`)
+9. Final `agenticros doctor` summary
 
 Pass `--force` to re-run every step regardless of state.
 
@@ -83,6 +85,43 @@ same report as a structured object for CI / scripting:
 
 Exits non-zero if any check is red.
 
+Checks include MCP server build status, OpenClaw plugin health, **Codex MCP config**
+(`~/.codex/config.toml` path and namespace policy), **Hermes MCP config**
+(`~/.hermes/config.yaml`), and Codex / Hermes CLI presence on `PATH`.
+
+### `agenticros codex setup [--project]`
+
+Register the AgenticROS MCP server for **OpenAI Codex CLI**:
+
+| Flag | Effect |
+|---|---|
+| (default) | Writes `[mcp_servers.agenticros]` to `~/.codex/config.toml` |
+| `--project` | Writes `.codex/config.toml` in the current repo root instead |
+
+Uses an **absolute path** to the MCP server binary (`packages/agenticros-claude-code/dist/index.js` in workspace mode, or the bundled path after `npx agenticros init`). Sets `AGENTICROS_ROBOT_NAMESPACE = ""` so `agenticros mode real|sim` drives the active robot namespace.
+
+Also offered as an optional step during `agenticros init`.
+
+### `agenticros codex doctor [--json]`
+
+Validate Codex MCP configuration: global and (when in a workspace) project `.codex/config.toml`, MCP binary path, and namespace policy. Exits non-zero on red checks. With `--json`, emits structured output for scripting.
+
+See **[docs/codex-setup.md](codex-setup.md)** for the full Codex onboarding guide.
+
+### `agenticros hermes setup`
+
+Register the AgenticROS MCP server for **[Hermes Agent](https://github.com/NousResearch/hermes-agent)**:
+
+Writes `mcp_servers.agenticros` to `~/.hermes/config.yaml` with an **absolute path** to the MCP server binary and `AGENTICROS_ROBOT_NAMESPACE: ""` so `agenticros mode real|sim` drives the active robot namespace.
+
+Also offered as an optional step during `agenticros init`. After setup, run `/reload-mcp` in Hermes or `hermes mcp test agenticros`.
+
+### `agenticros hermes doctor [--json]`
+
+Validate Hermes MCP configuration: `~/.hermes/config.yaml`, MCP binary path, and namespace policy. Exits non-zero on red checks. With `--json`, emits structured output for scripting.
+
+See **[docs/hermes-setup.md](hermes-setup.md)** for the full Hermes onboarding guide.
+
 ### `agenticros status [--json]`
 
 Shows running components (camera / sim / mcp / rosbridge / openclaw-gateway)
@@ -111,6 +150,9 @@ Read or edit `~/.agenticros/config.json`. Actions:
 |---|---|---|
 | `~/.agenticros/config.json` | User | AgenticROS runtime config (transport mode, namespace, safety limits). |
 | `~/.agenticros/cli-state.json` | CLI | Last-used mode/namespace for the menu's "(yesterday)" hint. |
+| `~/.hermes/config.yaml` | Hermes Agent | MCP server registrations (written by `agenticros hermes setup`). |
+| `~/.codex/config.toml` | Codex CLI | MCP server registrations (written by `agenticros codex setup`). |
+| `.codex/config.toml` | Codex CLI | Project-scoped MCP config (written by `agenticros codex setup --project`). |
 | `~/agenticros/` | CLI (npm-install mode) | Copy of the monorepo, with built dist + colcon install. |
 | `/tmp/agenticros-*.pid` | CLI | PIDs of background processes the CLI spawned. |
 | `/tmp/agenticros-*.log` | CLI | Stdout/stderr from those processes. |
@@ -140,7 +182,12 @@ Read or edit `~/.agenticros/config.json`. Actions:
 ## Troubleshooting
 
 - **`doctor` shows red checks** → run `agenticros init` to walk through every
-  step. Re-run `doctor` afterward.
+  step. Re-run `doctor` afterward. For Codex-specific issues, run
+  `agenticros codex doctor`. For Hermes, run `agenticros hermes doctor`.
+- **Codex `/mcp` does not list agenticros** → run `agenticros codex setup`
+  (absolute MCP path required). See [codex-setup.md](codex-setup.md).
+- **Hermes MCP tools missing** → run `agenticros hermes setup`, then `/reload-mcp`
+  in Hermes. See [hermes-setup.md](hermes-setup.md).
 - **`up` exits immediately** → `agenticros logs <component>` (the CLI now
   records where every child wrote its output) and read the error in context.
 - **`up sim-amr` warns "scripts/sim/run_sim.sh not found"** → simulation