{"id":50946653,"url":"https://github.com/agenticros/agenticros","last_synced_at":"2026-06-17T21:01:02.103Z","repository":{"id":341673611,"uuid":"1170068654","full_name":"agenticros/agenticros","owner":"agenticros","description":"ROS plugin for OpenClaw, Claude (Code,Desktop,Dispatch), Google Gemini, MCP, etc.","archived":false,"fork":false,"pushed_at":"2026-06-10T23:56:24.000Z","size":2139,"stargazers_count":74,"open_issues_count":1,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T00:08:48.673Z","etag":null,"topics":["ai","anthropic","claude-code","openclaw","robotics","ros"],"latest_commit_sha":null,"homepage":"https://agenticros.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agenticros.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-01T16:50:17.000Z","updated_at":"2026-06-10T23:56:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/agenticros/agenticros","commit_stats":null,"previous_names":["agenticros/agenticros"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agenticros/agenticros","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticros%2Fagenticros","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticros%2Fagenticros/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticros%2Fagenticros/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticros%2Fagenticros/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agenticros","download_url":"https://codeload.github.com/agenticros/agenticros/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agenticros%2Fagenticros/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34465322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","claude-code","openclaw","robotics","ros"],"created_at":"2026-06-17T21:00:23.483Z","updated_at":"2026-06-17T21:01:02.071Z","avatar_url":"https://github.com/agenticros.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgenticROS\n\n```text\n    _                     _   _       ____   ___  ____\n   / \\   __ _  ___ _ __ | |_(_) ___ |  _ \\ / _ \\/ ___|\n  / _ \\ / _` |/ _ \\ '_ \\| __| |/ __|| |_) | | | \\___ \\\n / ___ \\ (_| |  __/ | | | |_| | (__ |  _ \u003c| |_| |___) |\n/_/   \\_\\__, |\\___|_| |_|\\__|_|\\___||_| \\_\\___/|____/\n        |___/\n  AgenticROS - agentic AI for ROS-powered robots\n```\n\n**Physical AI Agents for ROS Robots**\n\n[![Watch the AgenticROS intro on YouTube](https://img.youtube.com/vi/_fbWhYcPj0M/maxresdefault.jpg)](https://www.youtube.com/watch?v=_fbWhYcPj0M)\n\n\u003e ▶ [Watch the AgenticROS intro on YouTube](https://www.youtube.com/watch?v=_fbWhYcPj0M)\n\nAgenticROS turns ROS 2 robots into agent-native machines. Speak, type, or message — and your robot perceives, reasons, and acts. It is an open, AI-agent-agnostic interface layer that bridges the world of frontier reasoning models with the world of cameras, depth sensors, motors, and `cmd_vel`, so robots stop being remote-controlled tools and start collaborating like teammates.\n\nWith AgenticROS, your robot can describe what it sees, follow intent (\"go check the front door\"), run skills you author, and respond to natural language across the agent platforms you already use. **One ROS 2 workspace, one config, many agents.**\n\n## Supported AI Agent platforms\n\n- **[OpenClaw](https://openclaw.ai)** — Native gateway plugin with ROS 2 tools, commands, a config UI, a teleop web app, and a skill loader. The flagship integration.\n- **[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.\n- **[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.\n- **[OpenAI Codex CLI](https://developers.openai.com/codex/)** — The same MCP server registers cleanly via `codex mcp add agenticros — node …/packages/agenticros-claude-code/dist/index.js`, or via a `[mcp_servers.agenticros]` entry in `~/.codex/config.toml`. Same 15 tools, same JSON shapes. Setup: [packages/agenticros-claude-code/README.md#codex-cli-openai](packages/agenticros-claude-code/README.md#codex-cli-openai).\n- **[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.\n\nAgenticROS 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.\n\n## Architecture\n\n![AgenticROS architecture: agent platforms → adapter packages → shared TypeScript runtime → transports → ROS 2 workspace and robot](docs/images/agenticros-architecture.png)\n\n- **Core** (`packages/core`): Platform-agnostic ROS2 transport (rosbridge, Zenoh, local, WebRTC), config schema, and shared types. No dependency on any specific AI platform.\n- **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.\n- `**packages/agenticros-claude-code`** — MCP server for **Claude Code** (terminal), **Claude desktop** (macOS), and **Dispatch** (iOS paired to Mac). See [packages/agenticros-claude-code/README.md](packages/agenticros-claude-code/README.md).\n- `**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).\n\n```\nUser (messaging app) → OpenClaw Gateway → AgenticROS OpenClaw plugin → Core → ROS2 robots\nClaude (Code / desktop / Dispatch) → agenticros MCP server → Core → ROS2 robots (Zenoh/rosbridge)\nGemini CLI → @agenticros/gemini (function calling) → Core → ROS2 robots\n```\n\n## A shared mission language for robots\n\nThe same tool surface across every adapter — Claude Code, Codex, Gemini, OpenClaw — so two different agents on two different stacks can both speak the same dialect when controlling the same robot. Built around five capabilities.\n\n### Capability manifests — robots advertise *verbs*\n\nEvery AgenticROS-enabled robot exposes a typed list of named verbs through `ros2_list_capabilities`: `drive_base`, `take_snapshot`, `measure_depth`, `find_object`, `follow_person`, plus whatever a [skill package](#skills) contributes. The agent plans against the verbs instead of raw ROS 2 topics — and the manifest is shaped to double as an ACP / A2A agent card.\n\n### Mission chaining — `run_mission`\n\nOne MCP tool, `run_mission`, executes a declarative step graph. Each step is `{ id, capability, inputs, on_fail }`. Outputs from any step flow into later steps via `{{stepId.outputs.field}}` template references — so a detection wires straight into the next motion command with no glue code:\n\n```json\n{\n  \"steps\": [\n    { \"id\": \"find\",     \"capability\": \"find_object\", \"inputs\": { \"target\": \"chair\" } },\n    { \"id\": \"approach\", \"capability\": \"drive_base\",\n      \"inputs\": {\n        \"linear_x\": 0.2,\n        \"angular_z\": \"{{find.outputs.horizontal_offset}}\"\n      }\n    }\n  ]\n}\n```\n\n### Natural-language goals\n\n`run_mission` also accepts a `goal` field — plain English. A rule-based, deterministic planner in `@agenticros/core` compiles it into a runnable mission against the robot's capability registry:\n\n- `\"take a picture\"` → `take_snapshot`\n- `\"follow me\"` → `follow_person`\n- `\"drive forward at 0.3 m/s\"` → `drive_base { linear_x: 0.3 }`\n- `\"find a chair and drive toward it\"` → the two-step compound plan above\n\nNo LLM dependency (the planner is a few hundred lines of pattern matching, so the runtime doesn't require Ollama) and no fabricated calls (it only emits capabilities actually in the registry). Uncompilable goals return a clean error with the recognised-verb list so the agent can self-correct.\n\n### Multi-robot fleets\n\n`ros2_list_robots`, `ros2_discover_robots`, and `ros2_find_robots_for({ capability, kind?, online? })` let an agent ask *\"give me an AMR that can `follow_person` and is currently online\"* and get back a ranked list. The CLI keeps fleet metadata in sync without hand-editing JSON:\n\n```bash\nagenticros robots add my-amr \\\n  --kind=amr --sensors=has_realsense,!has_arm \\\n  --capabilities=drive_base,take_snapshot,follow_person\n```\n\nOn the ROS side, every robot publishes a 1 Hz heartbeat on `\u003cns\u003e/agenticros/robot_info` so the online filter reflects what's actually reachable. A single mission can route different steps to different robots — *\"the AMR finds the box, the arm picks it up\"* runs as one mission.\n\n### Cancel + shared transcripts\n\n`mission_cancel({ mission_id })` flips an in-process cancellation token; the runner stops at the next step boundary and marks remaining steps `cancelled`. When the [shared memory backend](#memory-optional) is on, every step is also written to `mission:\u003cid\u003e` in long-term memory, tagged with `step:\u003cstatus\u003e` and `capability:\u003cid\u003e`. A different agent — different process, different vendor — can `memory_recall` later and reconstruct exactly what happened, so two agents can collaborate on or hand off a mission.\n\nFull architecture + design trade-offs: **[docs/strategy-ai-agents-plus-ros.md](docs/strategy-ai-agents-plus-ros.md)**.\n\n## Repository layout\n\n- `**packages/core**` — Transport, types, config (Zod). Used by all adapters.\n- `**packages/agenticros**` — OpenClaw plugin: tools, commands, config page, teleop routes.\n- `**packages/agenticros-claude-code**` — MCP server for Claude Code + Claude desktop / Dispatch (tools only; no config UI).\n- `**packages/agenticros-gemini**` — Gemini CLI (function calling; no MCP).\n- `**ros2_ws/**` — ROS2 workspace: `agenticros_msgs`, `agenticros_bringup` (Gazebo + RViz + rosbridge launches), `agenticros_discovery`, `agenticros_agent`, `agenticros_follow_me`.\n- `**docs/**` — Architecture, skills, robot setup, Zenoh, teleop.\n- `**scripts/**` — Workspace setup, gateway plugin config, run demos.\n- `**docker/**` — Docker Compose and Dockerfiles for ROS2 + plugin images.\n- `**examples/**` — Example projects.\n\n## Install\n\nYou only need one command. The `agenticros` CLI handles everything else —\ninstalling the ROS 2 workspace, building the MCP server, registering the\nOpenClaw plugin, and wiring up your robot config.\n\n```bash\nnpx agenticros\n```\n\nThat's it. Run it on any machine with **Node ≥ 20**, no `git clone` required.\nThe first run launches the interactive menu:\n\n```text\n╔──────────────────────────────────────────────────╗\n║  AgenticROS - agentic AI for ROS-powered robots  ║\n╚──────────────────────────────────────────────────╝\n\n? What would you like to do?\n  Launch with real robot\n❯ Launch with simulation\n  First-time setup (workspace + OpenClaw plugin + API key)\n  Manage skills (2 registered, 0 available, 0 broken)\n  Stop everything\n  Doctor (health check)\n  Configure (API keys, namespace, transport)\n  Tail logs\n```\n\nPick **First-time setup** once (workspace + OpenClaw plugin + API key, all\nidempotent), then choose how you want to run:\n\n| You want to … | Pick |\n|---|---|\n| Drive your **real robot** (RealSense + motors + MCP) | **Launch with real robot** |\n| Demo a **simulated 2-wheel AMR** in Gazebo + RViz | **Launch with simulation → AMR** |\n| Demo a **simulated 6-DOF arm** (UR5e-shaped, per-joint position control) | **Launch with simulation → 6-DOF arm** |\n\nOnce a stack is up, point any of the supported agents — OpenClaw, Claude Code,\nClaude Desktop / Dispatch, or Gemini CLI — at the same robot and start talking\nto it. The CLI tracks what it spawned (pidfiles + logs under `/tmp/agenticros-*`),\nso **Stop everything** cleanly tears the demo down.\n\nPrefer scripted invocations? Every menu item maps to a direct command:\n\n```bash\nnpx agenticros init             # one-time workspace + plugin + API key\nagenticros up real              # real robot stack\nagenticros up sim-amr           # simulated AMR (Gazebo + RViz, headless on Jetson)\nagenticros up sim-arm           # simulated 6-DOF arm\nagenticros mode \u003creal|sim\u003e      # swap the active config profile (namespace, transport)\nagenticros robots               # list / add / remove robots in the fleet (kind, sensors, capabilities)\nagenticros skills               # list / add / remove AgenticROS skills (see below)\nagenticros doctor               # coloured health check\nagenticros down                 # stop everything we started\n```\n\nFull CLI reference: **[packages/agenticros-cli/README.md](packages/agenticros-cli/README.md)**.\n\n### Requirements\n\n- **Node.js ≥ 20** (the only hard requirement — `npx agenticros` installs pnpm\n  itself if missing)\n- **ROS 2 Humble or Jazzy** if you plan to use the real-robot stack or any\n  simulation (the CLI sources `/opt/ros/\u003cdistro\u003e/setup.bash` and runs\n  `colcon build` for you)\n- **OpenClaw gateway** only if you also want the OpenClaw web UI / chat /\n  teleop adapter\n\n### Contributing / building from source\n\nHacking on the packages themselves? Clone and use the local checkout — the CLI\nauto-detects the workspace and uses live sources instead of the bundled snapshot:\n\n```bash\ngit clone https://github.com/PlaiPin/agenticros \u0026\u0026 cd agenticros\npnpm install \u0026\u0026 pnpm build\n./agenticros                    # repo-local CLI shim, same menu as `npx agenticros`\n```\n\nFor the OpenClaw plugin specifically, point the gateway at this repo's\n`packages/agenticros` and configure under `plugins.entries.agenticros.config`.\n**Recommended:** OpenClaw **2026.3.11+** — routes work at\n[http://127.0.0.1:18789/plugins/agenticros/](http://127.0.0.1:18789/plugins/agenticros/)\n(config, teleop). For local dev without token auth:\n`node scripts/setup-openclaw-local.cjs` then restart the gateway. Older gateways\nneeding token auth: run `node scripts/agenticros-proxy.cjs 18790` and open\n[http://127.0.0.1:18790/plugins/agenticros/](http://127.0.0.1:18790/plugins/agenticros/).\nSee **[docs/openclaw-releases-and-plugin-routes.md](docs/openclaw-releases-and-plugin-routes.md)**\nand **[docs/teleop.md](docs/teleop.md)**.\n\nSee **`docs/`** for robot setup, skills, teleop, simulation internals, and Docker.\n\n## RViz2 and Gazebo (TurtleBot3 + rosbridge)\n\nThe package `**agenticros_bringup`** provides launch files and an RViz2 config so you can run the same style of stack used in `**examples/turtlebot-chat**` and `**docker/**`: TurtleBot3 in Gazebo, `**/scan**`, `**/cmd_vel**`, and rosbridge on **port 9090** for the AgenticROS plugin.\n\n**Install** (Ubuntu / ROS 2 Jazzy): `sudo apt install ros-jazzy-turtlebot3-gazebo ros-jazzy-rviz2 ros-jazzy-rosbridge-suite` (or rely on the Docker image, which already includes them). `**colcon build` does not install this** — if you see `package 'turtlebot3_gazebo' not found`, run the `apt` line above, then verify with `ros2 pkg prefix turtlebot3_gazebo` after sourcing `/opt/ros/jazzy/setup.bash`.\n\nFor **namespaced** `cmd_vel` (same `robot.namespace` as the plugin in OpenClaw), pass `**robot_namespace:=\u003cid\u003e`** to the Gazebo bringup launches, or see [agenticros_bringup README](ros2_ws/src/agenticros_bringup/README.md#namespaced-cmd_vel-agenticros-robotnamespace).\n\n**Build** the workspace package (from `**ros2_ws`** after a full `colcon build`, or alone):\n\n```bash\ncd ros2_ws\nsource /opt/ros/jazzy/setup.bash\ncolcon build --packages-select agenticros_bringup\nsource install/setup.bash\n```\n\n**Commands** (after `source install/setup.bash`):\n\n\n| Goal                                                                          | Command                                                            |\n| ----------------------------------------------------------------------------- | ------------------------------------------------------------------ |\n| **Rosbridge + Gazebo** (headless-friendly; plugin uses `ws://localhost:9090`) | `ros2 launch agenticros_bringup rosbridge_gazebo.launch.py`        |\n| **Gazebo + RViz** on one machine (needs a display)                            | `ros2 launch agenticros_bringup turtlebot3_gazebo_rviz.launch.py`  |\n| **RViz only** (simulation already running)                                    | `ros2 launch agenticros_bringup rviz.launch.py use_sim_time:=true` |\n| **Gazebo only** (you start rosbridge yourself)                                | `ros2 launch agenticros_bringup gazebo_turtlebot3.launch.py`       |\n\n\n**Parameters**: e.g. `turtlebot3_model:=waffle`, or `rviz_config:=/path/to/custom.rviz` for the RViz launch.\n\n**Mode A (local DDS)** — OpenClaw and Gazebo on the **same machine**, plugin transport `**local`** (no rosbridge). Match `**ROS_DOMAIN_ID`** between the sim and the plugin (default `**0**`):\n\n```bash\nros2 launch agenticros_bringup mode_a_gazebo.launch.py\n# With RViz: ros2 launch agenticros_bringup mode_a_gazebo_rviz.launch.py\n```\n\nIn the AgenticROS config UI, set **Transport mode** to **local** and **Domain ID** to the same value as `ros_domain_id` (default `0`). Then drive the robot with the usual tools (e.g. `ros2_publish` on `/cmd_vel`).\n\n**Docker** (starts Gazebo + TurtleBot3 + rosbridge — typical for **Mode B** plugin on host → `ws://localhost:9090`):\n\n```bash\ncd docker\ndocker compose -f docker-compose.yml -f docker-compose.sim.yml up ros2\n```\n\nThen configure the AgenticROS plugin with `**ws://localhost:9090**` as usual. The bundled RViz config is `**turtlebot3_agenticros.rviz**` (fixed frame `**odom**`, LaserScan `**/scan**`, RobotModel from `**/robot_description**`). Adjust displays in RViz if your robot uses different topic names.\n\nDetails: [ros2_ws/src/agenticros_bringup/README.md](ros2_ws/src/agenticros_bringup/README.md).\n\n## Running AgenticROS on NemoClaw\n\n[NVIDIA NemoClaw](https://github.com/NVIDIA/NemoClaw) packages OpenClaw inside an OpenShell sandbox container with policy-enforced egress and managed inference. AgenticROS plugs into that OpenClaw the same way it plugs into a \"vanilla\" gateway — with one twist: ROS 2, RealSense, and rosbridge run on the **host**, and only the AgenticROS plugin runs **inside** the sandbox. The plugin reaches the host over the Docker bridge at `host.docker.internal:9090`.\n\nQuick steps (sandbox named `nemo`, robot has namespace `\u003cNS\u003e`):\n\n```bash\n# 1. Build + pack the plugin so it works in the sandbox's offline-npm env\npnpm install \u0026\u0026 pnpm build\npnpm --filter @agenticros/agenticros deploy --prod /tmp/agenticros-deploy\nrm -f /tmp/agenticros-deploy/node_modules/.pnpm/node_modules/@agenticros/agenticros\n\n# 2. Copy it into the sandbox and chown to the sandbox user\nCONTAINER=$(docker ps --format '{{.Names}}' | grep '^openshell-nemo-')\ndocker exec \"$CONTAINER\" rm -rf /sandbox/agenticros \u0026\u0026 docker exec \"$CONTAINER\" mkdir -p /sandbox/agenticros\ndocker cp /tmp/agenticros-deploy/. \"$CONTAINER:/sandbox/agenticros/\"\ndocker exec \"$CONTAINER\" chown -R sandbox:sandbox /sandbox/agenticros\n\n# 3. Register + configure the plugin inside the sandbox (HOME=/sandbox is required)\ndocker exec -u sandbox -e HOME=/sandbox \"$CONTAINER\" \\\n    openclaw plugins install -l /sandbox/agenticros           # Ctrl-C once it starts logging \"ROS2 transport status:\"\n\n# 4. Open the host's rosbridge port in NemoClaw policy\nnemoclaw nemo policy-add --from-file scripts/agenticros-rosbridge.policy.yaml --yes\n\n# 5. Start RealSense + rosbridge on the host\n./scripts/run_nemoclaw_host_stack.sh humble robot_namespace:=\u003cNS\u003e align_depth:=true\n\n# 6. Restart the sandbox gateway, verify, and chat\nnemoclaw nemo recover\n./scripts/smoke_test_nemoclaw.sh        # 6 checks; exits 0 when all green\nnemoclaw nemo dashboard-url\n```\n\nFull walkthrough, troubleshooting, and a \"full-embed\" alternative (ROS / RealSense baked into a custom sandbox image): **[docs/nemoclaw.md](docs/nemoclaw.md)**.\n\n## Claude + AgenticROS (MCP)\n\nThe 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**.\n\nShared setup:\n\n1. **Build** (from repo root): `pnpm install \u0026\u0026 pnpm build`\n2. **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)).\n3. **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).\n\nOptional: 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).\n\n### Claude Code CLI (terminal)\n\n1. **Register MCP** (project scope, from repo root):\n  ```bash\n   claude mcp add --transport stdio --scope project agenticros -- node packages/agenticros-claude-code/dist/index.js\n  ```\n   Or add the server via `.mcp.json` in the repo. To avoid multiple MCP processes, run `pnpm mcp:kill` before starting a fresh `claude` session after rebuilding.\n2. **Run**: `claude` — e.g. “List ROS2 topics”, “What do you see?”, “Publish a stop to cmd_vel.”\n\n### Claude desktop app + Dispatch (iOS)\n\nClaude Code stores MCP in `~/.claude.json` or project `.mcp.json`. The **Claude desktop app** uses a separate file:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n1. Copy your **agenticros** MCP entry from Claude Code / `.mcp.json` into `mcpServers` in `claude_desktop_config.json`.\n2. Use an **absolute path** to `packages/agenticros-claude-code/dist/index.js` (the desktop app’s working directory is not your repo root, so relative `node packages/...` paths will fail).\n3. **Fully quit** the Claude desktop app (not just close the window) and reopen it. The **agenticros** tools should appear in the desktop app and in **Dispatch** when your phone is paired to Claude on the Mac.\n\nExample `mcpServers` entry (adjust the path and namespace to your machine):\n\n```json\n{\n  \"mcpServers\": {\n    \"agenticros\": {\n      \"command\": \"sh\",\n      \"args\": [\n        \"-c\",\n        \"node /ABSOLUTE/PATH/TO/agenticros/packages/agenticros-claude-code/dist/index.js 2\u003e\u003e/tmp/agenticros-mcp.log\"\n      ],\n      \"env\": {\n        \"AGENTICROS_ROBOT_NAMESPACE\": \"robotYOUR_NAMESPACE_NO_DASHES\"\n      }\n    }\n  }\n}\n```\n\nFull steps, permissions (`mcp__agenticros`), and troubleshooting are in **[packages/agenticros-claude-code/README.md](packages/agenticros-claude-code/README.md)**.\n\n## Gemini CLI\n\nUse **Google Gemini** to chat with your robot from the terminal (same ROS2 tools as Claude Code, no MCP).\n\n1. **Build**: `pnpm install \u0026\u0026 pnpm build`\n2. **Config**: Same as Claude Code — `~/.agenticros/config.json` with `zenoh.routerEndpoint`, `robot.namespace`, etc.\n3. **Run**: Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) and run:\n  ```bash\n   GEMINI_API_KEY=xxx pnpm --filter @agenticros/gemini exec agenticros-gemini \"What do you see?\"\n  ```\n\nSee **[packages/agenticros-gemini/README.md](packages/agenticros-gemini/README.md)** for details and tested command examples (camera snapshot/description, depth distance, forward Twist, and stop).\n\n## Memory (optional)\n\nAgenticROS 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:\n\n- **`local`** — zero deps, JSON-on-disk at `~/.agenticros/memory.json`, keyword + recency search. Enable with one config flag.\n- **`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.\n\nWhen enabled, every adapter exposes four tools — `memory_remember`, `memory_recall`, `memory_forget`, `memory_status`. OpenClaw chats additionally get a system-context section that lists recently-remembered facts and instructs the LLM to call `memory_recall` before answering personal-context questions like *\"what do I have for X?\"* or *\"what's my Y?\"*.\n\nMemory is namespaced by `robot.namespace` so adapters talking to the same robot share the same store. See **[docs/memory.md](docs/memory.md)** for ready-to-paste recipes, cross-process verification steps, and troubleshooting. OpenClaw users can also enable it from the web config UI at `/agenticros/config` (Memory section).\n\nQuickest path to try it (fully local, no API keys):\n\n```bash\npnpm add mem0ai\nollama pull nomic-embed-text   # ~270 MB embedder model\n```\n\nAdd `{ \"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.\n\n## Skills\n\nAgenticROS **skills** are optional packages that add tools and behaviors to the plugin (e.g. `follow_robot`, `find_object`). They are loaded at OpenClaw gateway start. **[AgenticROS Skills](https://github.com/agenticros/agenticros-skills)** is a curated list — use it to discover skills for your robot and to submit your own.\n\n### Managing skills with the CLI\n\nThe `agenticros skills` command (and the **Manage skills** menu entry) does everything for you: it scans the usual locations for clones, edits `~/.openclaw/openclaw.json`, refreshes the plugin manifest's `contracts.tools` allowlist, and reminds you to bounce the gateway.\n\n```bash\nagenticros skills                       # list registered + cloned-but-unregistered\nagenticros skills discover              # interactive picker over candidates on disk\nagenticros skills add \u003cpath-or-name\u003e    # register a clone (path) or npm package\nagenticros skills remove \u003cid-or-name\u003e   # unregister\nagenticros skills sync                  # refresh OpenClaw contracts.tools allowlist\n```\n\nA typical first-run looks like:\n\n```bash\n# clone whichever skills you want, anywhere near the repo\ncd ~/Projects\ngit clone https://github.com/agenticros/agenticros-skill-followme\ngit clone https://github.com/agenticros/agenticros-skill-find\n\n# build them (skills compile independently of the main workspace)\ncd agenticros-skill-followme \u0026\u0026 pnpm install \u0026\u0026 pnpm build \u0026\u0026 cd ..\ncd agenticros-skill-find     \u0026\u0026 pnpm install \u0026\u0026 pnpm build \u0026\u0026 cd ..\n\n# register both — short ids resolve against the discovered clones\nagenticros skills add followme\nagenticros skills add find\nagenticros skills sync                  # update contracts.tools\nsystemctl --user restart openclaw-gateway.service\n```\n\n`agenticros skills` then shows them as registered, and `agenticros doctor` includes a skills health-check that flags any clone that hasn't been built or whose `skillPaths` entry no longer exists.\n\nListing output:\n\n```text\n╔─────────────────────╗\n║  AgenticROS skills  ║\n╚─────────────────────╝\n\n› OpenClaw config: /home/you/.openclaw/openclaw.json\n\nRegistered:\n  ● followme  agenticros-skill-followme\n      via path  →  /home/you/Projects/agenticros-skill-followme\n  ● find      agenticros-skill-find\n      via path  →  /home/you/Projects/agenticros-skill-find\n```\n\n### What the CLI writes\n\n- `~/.openclaw/openclaw.json` → `plugins.entries.agenticros.config.skillPaths[]` and `.skillPackages[]` (the only place the plugin actually reads from at gateway start).\n- `packages/agenticros/openclaw.plugin.json` → `contracts.tools` allowlist via `scripts/sync-skill-tools.mjs`. Required on OpenClaw **2026+**, which silently drops any tool a plugin registers but hasn't declared.\n\nPer-skill behaviour lives under `config.skills.\u003cskillId\u003e` (e.g. `config.skills.followme.depthTopic`). The CLI doesn't auto-write these — use `agenticros config set skills.find.confidence=0.5` or edit `~/.openclaw/openclaw.json` directly. See each skill's README for its options.\n\n### Contract \u0026 writing your own skill\n\nA skill is a Node package with an `\"agenticros\": { \"id\": \"...\" }` block in `package.json` and a `registerSkill(api, config, context)` export from `main`. Publish it to **[skills.agenticros.com](https://skills.agenticros.com)** so others can install it with `npx agenticros skills install \u003cslug\u003e`. See **[docs/skills.md](docs/skills.md)** for the full contract and **[agenticros-skill-followme](https://github.com/agenticros/agenticros-skill-followme)** as a reference template.\n\n## Strategy \u0026 vision\n\nWhere AgenticROS is going next — beyond the shared mission language above, the roadmap covers turning capability manifests into agent cards on the wire (WebRTC / A2A so a robot can register itself as an agent in a mesh), an LLM-backed planner behind the existing `compileGoalToMission` contract, the `skills.agenticros.com` marketplace with declarative auto-fetch and in-agent installs, spatial memory, and cross-vendor agent collaboration via ACP / A2A: **[docs/strategy-ai-agents-plus-ros.md](docs/strategy-ai-agents-plus-ros.md)**.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenticros%2Fagenticros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagenticros%2Fagenticros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagenticros%2Fagenticros/lists"}