agenticros

agentic AI for ROS-powered robots

agenticros is the unified command-line tool for AgenticROS — bring up a real robot or a simulated one, drive it from Claude Code / OpenClaw, and keep your workspace healthy from a single binary.

# Brand new machine: one command end-to-end
npx agenticros init     # workspace + plugin + API key + doctor
agenticros              # interactive menu
agenticros up real      # bring up the real-robot stack
agenticros up sim-amr   # bring up a simulated 2-wheel AMR
agenticros up sim-arm   # bring up a simulated 6-DOF arm
agenticros doctor       # health check
agenticros down         # stop everything we started

Why this exists

Before agenticros, the demo path was a chain of shell scripts: start_demo.sh, setup_gateway_plugin.sh, configure_agenticros.sh, onboard_robot.sh, … Each one solved a real problem but the cumulative surface area was a barrier for new users and a brittle handoff for demos.

The CLI is the single entry point. It orchestrates the existing scripts rather than replacing them, so they remain usable on their own. The published npm tarball bundles those scripts plus the ROS 2 source packages and the pre-built MCP server, so npx agenticros init works on a fresh machine with no git clone step.

Install

Three ways, listed easiest first:

1. npx agenticros — one command on any machine with Node ≥ 20. Pulls the latest published tarball, no local checkout required.
2. Per-user global — npm install -g agenticros (or pnpm add -g agenticros). Then agenticros is on your PATH from any working directory.
3. Repo checkout (contributors) — git clone … && pnpm install && pnpm build, then run the root ./agenticros shim. The CLI auto-detects the workspace and uses live scripts / sources instead of the bundled snapshots.

Commands

| Command | Purpose | |---|---| | agenticros | Interactive top-level menu. | | agenticros init | First-time setup wizard. Idempotent. | | agenticros up real | Bring up the real-robot stack (RealSense + motors + MCP). | | agenticros up sim-amr | Bring up the simulated 2-wheel AMR. | | agenticros up sim-arm | Bring up the simulated 6-DOF arm (UR5e-shaped, per-joint position control). | | agenticros down | Stop everything we started. | | agenticros doctor | Coloured health-check table; --json for CI. | | agenticros status | Snapshot of running components + last mode. | | agenticros logs [target] | Tail camera / mcp / sim / rosbridge / gateway. | | agenticros config [show\|set\|edit\|reset] | Read or edit ~/.agenticros/config.json. | | agenticros --help | Full help text. |

How init works

agenticros init is the wizard the menu's "First-time setup" entry runs. It walks through:

1. JS workspace deps (pnpm install)
2. JS workspace build (pnpm build)
3. ROS 2 workspace build (colcon build --symlink-install)
4. OpenClaw plugin install (scripts/setup_gateway_plugin.sh)
5. Robot config (namespace, transport mode, sample ~/.agenticros/config.json)
6. OpenAI API key (paste once → scripts/configure_agenticros.sh)
7. Final agenticros doctor summary

Every step is idempotent: it checks doctor first and skips the work if nothing is missing. Use agenticros init --force to redo everything.

Where state lives

• ~/.agenticros/config.json — AgenticROS runtime config (transport mode, robot namespace, safety limits, teleop defaults). Edited via agenticros config.
• ~/.agenticros/cli-state.json — CLI's own state (last mode, last namespace, for the menu's "(yesterday)" hint).
• ~/agenticros/ — the install dir when invoked via npx. Contains a copy of scripts/, ros2_ws/src/agenticros_*, the pre-built MCP, and sample configs. Skipped in repo-checkout mode.
• /tmp/agenticros-*.pid and /tmp/agenticros-*.log — pidfiles and logs for the background processes the CLI spawns (camera, sim, MCP, …). Same convention as the legacy scripts/start_demo.sh.

Contributing

See the monorepo README.md and CLAUDE.md at the repository root for the architecture overview. The CLI source lives at packages/agenticros-cli/; per-command sources are under src/commands/, shared helpers under src/util/, and runners (the subprocess glue around the existing shell scripts) under src/runners/.