agenticros 0.3.1 → 0.3.4

package/dist/util/mcp-setup.js

@@ -0,0 +1,235 @@
+/**
+ * Unified MCP host setup for Codex, Hermes, and Claude (Option C).
+ *
+ * All hosts register the same `@agenticros/claude-code` stdio server with an
+ * absolute path and empty AGENTICROS_ROBOT_NAMESPACE.
+ */
+import { execa } from "execa";
+import { buildCodexDoctorChecks, globalCodexConfigPath, projectCodexConfigPath, writeCodexAgenticrosConfig, } from "./codex-config.js";
+import { buildHermesDoctorChecks, globalHermesConfigPath, writeHermesAgenticrosConfig, } from "./hermes-config.js";
+import { buildClaudeDoctorChecks, claudeDesktopConfigPath, projectMcpJsonPath, writeClaudeAgenticrosConfig, } from "./claude-config.js";
+import { findMcpEntry } from "./mcp-discovery.js";
+import { colors, info, ok, warn, err } from "./logger.js";
+export async function codexOnPath() {
+    try {
+        const { exitCode } = await execa("codex", ["--version"], { reject: false });
+        return exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function hermesOnPath() {
+    try {
+        const { exitCode } = await execa("hermes", ["--version"], { reject: false });
+        return exitCode === 0;
+    }
+    catch {
+        try {
+            const { exitCode } = await execa("hermes", ["--help"], { reject: false });
+            return exitCode === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export async function claudeOnPath() {
+    try {
+        const { exitCode } = await execa("claude", ["--version"], { reject: false });
+        return exitCode === 0;
+    }
+    catch {
+        try {
+            const { exitCode } = await execa("claude", ["--help"], { reject: false });
+            return exitCode === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export function resolveMcpHosts(opts) {
+    if (opts.codexScope === "project" && opts.codex !== false) {
+        return ["codex"];
+    }
+    const explicit = ["codex", "hermes", "claude"].filter((h) => opts[h]);
+    if (explicit.length > 0)
+        return [...explicit];
+    if (opts.all !== false)
+        return ["codex", "hermes", "claude"];
+    return ["codex", "hermes", "claude"];
+}
+export function requireMcpEntry() {
+    const mcpEntry = findMcpEntry();
+    if (!mcpEntry) {
+        err("AgenticROS MCP server is not built.");
+        info("Run `pnpm --filter @agenticros/claude-code build` or `agenticros init` first.");
+        process.exit(1);
+    }
+    return mcpEntry;
+}
+export function setupCodexMcp(mcpEntry, scope, cwd) {
+    const configPath = scope === "global" ? globalCodexConfigPath() : projectCodexConfigPath(cwd);
+    writeCodexAgenticrosConfig(configPath, mcpEntry, { namespace: "" });
+    return configPath;
+}
+export function setupHermesMcp(mcpEntry) {
+    const configPath = globalHermesConfigPath();
+    writeHermesAgenticrosConfig(configPath, mcpEntry, { namespace: "" });
+    return configPath;
+}
+export function setupClaudeMcp(mcpEntry, target, cwd) {
+    const configPath = target === "project" ? projectMcpJsonPath(cwd) : claudeDesktopConfigPath();
+    writeClaudeAgenticrosConfig(configPath, mcpEntry, { namespace: "" });
+    return configPath;
+}
+export async function mcpSetupCommand(opts = {}) {
+    const mcpEntry = requireMcpEntry();
+    const hosts = resolveMcpHosts(opts);
+    const repoRoot = opts.repoRoot;
+    const cwd = opts.cwd ?? process.cwd();
+    if (!opts.quiet) {
+        info(`Configuring AgenticROS MCP for: ${hosts.join(", ")}`);
+        info(`MCP server: ${mcpEntry}\n`);
+    }
+    const written = [];
+    const explicitHosts = ["codex", "hermes", "claude"].filter((h) => opts[h]);
+    const isFullSetup = explicitHosts.length === 0 || explicitHosts.length === 3;
+    if (hosts.includes("codex")) {
+        if (opts.codexScope === "project") {
+            written.push(setupCodexMcp(mcpEntry, "project", repoRoot ?? cwd));
+        }
+        else {
+            written.push(setupCodexMcp(mcpEntry, "global"));
+            if (opts.project || (isFullSetup && repoRoot)) {
+                written.push(setupCodexMcp(mcpEntry, "project", repoRoot ?? cwd));
+            }
+        }
+    }
+    if (hosts.includes("hermes")) {
+        written.push(setupHermesMcp(mcpEntry));
+    }
+    if (hosts.includes("claude")) {
+        const desktopOnly = opts.desktop && !opts.project;
+        const projectOnly = opts.project && !opts.desktop;
+        if (!projectOnly) {
+            written.push(setupClaudeMcp(mcpEntry, "desktop"));
+        }
+        if (!desktopOnly && (opts.project || (isFullSetup && repoRoot) || projectOnly)) {
+            written.push(setupClaudeMcp(mcpEntry, "project", repoRoot ?? cwd));
+        }
+    }
+    for (const path of written) {
+        ok(`Wrote: ${path}`);
+    }
+    if (hosts.includes("codex")) {
+        const hasCodex = await codexOnPath();
+        if (hasCodex) {
+            info("Codex CLI detected — verify with `/mcp` in a Codex session.");
+        }
+        else {
+            warn("Codex CLI not on PATH.");
+        }
+    }
+    if (hosts.includes("hermes")) {
+        const hasHermes = await hermesOnPath();
+        if (hasHermes) {
+            info("Hermes detected — run `/reload-mcp` or `hermes mcp test agenticros`.");
+        }
+        else {
+            warn("Hermes CLI not on PATH.");
+        }
+    }
+    if (hosts.includes("claude")) {
+        const hasClaude = await claudeOnPath();
+        if (hasClaude) {
+            info("Claude Code CLI detected — run `claude` from the project with `.mcp.json`.");
+        }
+        else {
+            warn("Claude CLI not on PATH (Desktop config may still apply).");
+        }
+        info("Restart Claude Desktop fully (Cmd+Q) after desktop config changes.");
+    }
+}
+export function buildMcpDoctorChecks(mcpEntryExpected, repoRoot, hosts) {
+    const active = hosts ?? ["codex", "hermes", "claude"];
+    const checks = [];
+    if (active.includes("codex")) {
+        checks.push(...buildCodexDoctorChecks(mcpEntryExpected, repoRoot));
+    }
+    if (active.includes("hermes")) {
+        checks.push(...buildHermesDoctorChecks(mcpEntryExpected));
+    }
+    if (active.includes("claude")) {
+        checks.push(...buildClaudeDoctorChecks(mcpEntryExpected, repoRoot));
+    }
+    return checks;
+}
+export async function mcpDoctorCommand(opts = {}) {
+    const mcpEntry = findMcpEntry();
+    const hosts = opts.hosts ?? ["codex", "hermes", "claude"];
+    const checks = buildMcpDoctorChecks(mcpEntry, opts.repoRoot, hosts);
+    const cliChecks = [];
+    if (hosts.includes("codex")) {
+        const on = await codexOnPath();
+        cliChecks.push({
+            id: "codex-cli",
+            label: on ? "Codex CLI installed" : "Codex CLI not detected",
+            severity: on ? "green" : "yellow",
+            hint: on ? undefined : "Install from https://developers.openai.com/codex/",
+        });
+    }
+    if (hosts.includes("hermes")) {
+        const on = await hermesOnPath();
+        cliChecks.push({
+            id: "hermes-cli",
+            label: on ? "Hermes CLI installed" : "Hermes CLI not detected",
+            severity: on ? "green" : "yellow",
+            hint: on ? undefined : "Install from https://github.com/NousResearch/hermes-agent",
+        });
+    }
+    if (hosts.includes("claude")) {
+        const on = await claudeOnPath();
+        cliChecks.push({
+            id: "claude-cli",
+            label: on ? "Claude Code CLI installed" : "Claude Code CLI not detected",
+            severity: on ? "green" : "yellow",
+            hint: on ? undefined : "Install from https://claude.com/product/claude-code",
+        });
+    }
+    const allChecks = [...checks, ...cliChecks];
+    const exitCode = allChecks.some((c) => c.severity === "red")
+        ? 1
+        : allChecks.some((c) => c.severity === "yellow")
+            ? 0
+            : 0;
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ hosts, mcpEntry, checks: allChecks }, null, 2) + "\n");
+        return allChecks.some((c) => c.severity === "red") ? 1 : 0;
+    }
+    if (!opts.quiet) {
+        process.stdout.write(`${colors.bold("MCP doctor")}\n`);
+        if (!mcpEntry) {
+            err("MCP server not built.");
+            return 1;
+        }
+        info(`Expected MCP entry: ${mcpEntry}\n`);
+    }
+    for (const c of allChecks) {
+        const icon = c.severity === "green"
+            ? colors.green("✓")
+            : c.severity === "red"
+                ? colors.red("✗")
+                : colors.yellow("○");
+        process.stdout.write(`  ${icon} ${c.label}\n`);
+        if ("detail" in c && c.detail) {
+            process.stdout.write(`     ${colors.dim(c.detail)}\n`);
+        }
+        if (c.hint) {
+            process.stdout.write(`     ${colors.dim("→ " + c.hint)}\n`);
+        }
+    }
+    return allChecks.some((c) => c.severity === "red") ? 1 : 0;
+}
+//# sourceMappingURL=mcp-setup.js.map

package/dist/util/mcp-setup.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenticros",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "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-06T14:26:08.936Z",
   "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,8 @@ 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. MCP client config (optional — `agenticros mcp setup` for Codex, Hermes, and Claude)
+8. Final `agenticros doctor` summary
 
 Pass `--force` to re-run every step regardless of state.
 
@@ -83,6 +84,81 @@ 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, **MCP client configs**
+(Codex, Hermes, Claude — path and namespace policy), and CLI presence on `PATH`.
+
+### `agenticros mcp setup [--codex] [--hermes] [--claude] [--project] [--desktop]`
+
+**Primary command** — register the AgenticROS MCP server for all MCP clients at once:
+
+| Flag | Effect |
+|---|---|
+| (default) | Codex (`~/.codex/config.toml` + project `.codex/config.toml`), Hermes (`~/.hermes/config.yaml`), Claude Desktop + project `.mcp.json` |
+| `--codex` | Codex global config only |
+| `--hermes` | Hermes global config only |
+| `--claude` | Claude Desktop + project `.mcp.json` |
+| `--project` | Also write project-scoped Codex / Claude configs |
+| `--desktop` | With `--claude`, Claude Desktop config only |
+
+Uses an **absolute path** to the MCP server binary. Sets `AGENTICROS_ROBOT_NAMESPACE` empty so `agenticros mode real|sim` drives the active robot namespace.
+
+Also offered as an optional step during `agenticros init`.
+
+See **[docs/mcp-setup.md](mcp-setup.md)** for the unified onboarding guide.
+
+### `agenticros mcp doctor [--json] [--codex] [--hermes] [--claude]`
+
+Validate MCP configuration for Codex, Hermes, and Claude. Exits non-zero on red checks.
+
+### `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 claude setup [--desktop] [--project]`
+
+Register the AgenticROS MCP server for **Claude Code** and **Claude Desktop**:
+
+| Flag | Effect |
+|---|---|
+| (default) | Claude Desktop config + project `.mcp.json` (when in a repo) |
+| `--desktop` | `claude_desktop_config.json` only |
+| `--project` | `.mcp.json` in repo root only |
+
+Alias for `agenticros mcp setup --claude`. Restart Claude Desktop fully after desktop config changes.
+
+### `agenticros claude doctor [--json]`
+
+Validate Claude MCP configuration (desktop + project `.mcp.json`). Exits non-zero on red checks.
+
 ### `agenticros status [--json]`
 
 Shows running components (camera / sim / mcp / rosbridge / openclaw-gateway)
@@ -111,6 +187,11 @@ 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 mcp setup` or `agenticros hermes setup`). |
+| `~/.codex/config.toml` | Codex CLI | MCP server registrations (written by `agenticros mcp setup` or `agenticros codex setup`). |
+| `.codex/config.toml` | Codex CLI | Project-scoped MCP config (written by `agenticros mcp setup` or `agenticros codex setup --project`). |
+| `.mcp.json` | Claude Code | Project-scoped MCP config (written by `agenticros mcp setup` or `agenticros claude setup`). |
+| `~/Library/Application Support/Claude/claude_desktop_config.json` | Claude Desktop | MCP server registrations (written by `agenticros mcp setup` or `agenticros claude setup --desktop`). |
 | `~/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 +221,13 @@ 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 MCP-specific issues, run
+  `agenticros mcp doctor` (or `agenticros codex doctor`, `agenticros hermes doctor`, `agenticros claude doctor`).
+- **MCP tools missing in any client** → run `agenticros mcp setup`. See [mcp-setup.md](mcp-setup.md).
+- **Codex `/mcp` does not list agenticros** → run `agenticros mcp setup --codex`
+  (absolute MCP path required). See [codex-setup.md](codex-setup.md).
+- **Hermes MCP tools missing** → run `agenticros mcp setup --hermes`, 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

package/runtime/packages/agenticros-claude-code/README.md

@@ -136,6 +136,41 @@ Two Codex-specific notes:
 - **Absolute path required.** Codex's working directory at server-spawn time is not the AgenticROS repo root, so `args = ["packages/agenticros-claude-code/dist/index.js"]` will fail. Use the full absolute path.
 - **Project-scoped config.** Codex also supports a `.codex/config.toml` in a project directory (and a `mcp.json` in cwd on recent builds) — handy for per-repo MCP setups when you don't want `agenticros` enabled globally. See OpenAI's [Codex config reference](https://developers.openai.com/codex/config-reference) for the precedence rules.
 
+## Hermes Agent
+
+The same MCP server works unmodified with **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — Hermes is a model-agnostic MCP client (OpenRouter, Ollama, Anthropic, OpenAI, 200+ providers).
+
+**Option A — `agenticros hermes setup` (recommended)**
+
+```bash
+agenticros hermes setup
+agenticros hermes doctor
+```
+
+**Option B — edit YAML directly**
+
+```yaml
+# ~/.hermes/config.yaml
+mcp_servers:
+  agenticros:
+    command: "node"
+    args: ["/ABSOLUTE/PATH/TO/agenticros/packages/agenticros-claude-code/dist/index.js"]
+    env:
+      AGENTICROS_ROBOT_NAMESPACE: ""
+    connect_timeout: 60
+    timeout: 120
+```
+
+Then `/reload-mcp` in Hermes or restart the agent. Verify with `hermes mcp test agenticros`.
+
+Hermes-specific notes:
+
+- **Absolute path required.** Same as Codex — Hermes does not spawn MCP servers from the repo root.
+- **Empty namespace.** Leave `AGENTICROS_ROBOT_NAMESPACE: ""` so `agenticros mode real|sim` drives the active robot (same policy as Codex).
+- **Model choice is independent.** OpenRouter, Ollama, or any other Hermes LLM provider does not change AgenticROS MCP setup.
+
+Full guide: [docs/hermes-setup.md](../../docs/hermes-setup.md).
+
 ## Claude desktop app + Claude Dispatch (iOS)
 
 The Claude **desktop** app uses a different MCP config file than Claude Code: