ros-claw/rosclaw

1. What this repository is

ROSClaw is a Python 3.11+ runtime infrastructure for embodied agents, not a single robotics app. The repo is organized around a controlled execution loop for physical AI: define the robot body, route capabilities, validate actions in a sandbox, execute through a runtime adapter, then record and learn from the result.

2. Top-level control plane

The entry points are the CLI (src/rosclaw/cli.py, src/rosclaw/__main__.py) and the firstboot/dashboard tooling. These bootstrap the workspace, validate the installation, and connect the user to the rest of the runtime. The bin/rosclaw script and scripts/ folder support local installs, CI, and smoke tests.

3. Core runtime backbone

src/rosclaw/core/ provides the generic infrastructure: runtime lifecycle, async utilities, typed events, and the central EventBus. This is the main internal communication boundary; higher-level modules publish and subscribe to events rather than coupling directly.

4. Body and embodiment layer

src/rosclaw/body/, src/rosclaw/eurdf/, src/rosclaw/e_urdf/, and src/rosclaw/eurdf_zoo/ model the robot and its capabilities. This layer compiles and validates embodiment descriptions, safety constraints, references, ROS introspection, and fleet compatibility. The e-urdf-zoo/ directory contains concrete robot profiles and simulation assets for bodies like UR5e, Unitree G1/Go2, Fetch, Franka, and drones.

5. Capability routing and providers

src/rosclaw/provider/ is the policy boundary between intent and action. Providers expose capabilities, apply schema and action guards, and route requests into supported runtimes (python_runtime, http_runtime, ros2_runtime). Built-ins include skill, critic, VLM, and DeepSeek adapters. The key architectural rule is that model output does not directly command hardware; it must pass the provider/guard pipeline first.

6. Sandbox and execution boundary

src/rosclaw/sandbox/ and src/rosclaw/firewall/ enforce the action gate. The sandbox wraps execution, publishes events, and routes through a firewall that can allow, modify, block, or require confirmation. This is where unsafe actions are intercepted before they reach real or simulated hardware.

7. Physical execution adapters

src/rosclaw/mcp_drivers/, src/rosclaw/connectors/ros/, src/rosclaw/runtime/, and src/rosclaw/mcp/ bridge ROSClaw to actual execution environments. They include ROS 2 transport/bridge support, mock transport, serial drivers, MuJoCo and ManiSkill adapters, ROS discovery/normalization, and MCP server tooling. This is the boundary to ROS graphs, simulators, and hardware-facing services.

8. Observation, sensing, and readiness

src/rosclaw/sense/ collects telemetry and evaluates robot state. It includes collectors for ROS2, DDS, file replay, and mock sources; estimators for health, fatigue, readiness, envelope, and risk; and adapters that feed context into other subsystems. This layer turns raw robot/runtime signals into decision-ready status.

9. Practice, memory, and knowledge

src/rosclaw/practice/, src/rosclaw/memory/, and src/rosclaw/know/ form the learning and evidence plane. Practice records episodes and timelines, Memory provides persistence/search over experience traces, and Know stores structured task cards, embodiment cards, verifier cards, and evidence graphs. Together they preserve what happened and why it mattered.

10. How / recovery and intervention

src/rosclaw/how/ implements runtime intervention and recovery loops. It uses evidence, rules, and safety routing to propose repairs when execution goes wrong. This is the “self-healing” layer: it does not execute blindly, but reacts to failures using recorded traces and policy.

11. Auto, Darwin, and skill evolution

src/rosclaw/auto/ is the experimentation and patch-evolution system: diagnosis, hypothesis/proposal, patch validation, runners, promotion/rollback, and reporting. src/rosclaw/darwin/ provides evaluation scenarios, metrics, and plugin integration for benchmark-style validation. These subsystems decide whether a change is a champion, a dead end, or needs rollback.

12. Asset registry and onboarding

src/rosclaw/hub/ is the asset hub client/server logic for publishing, resolving, verifying, and installing versioned assets such as skills, providers, hardware MCP servers, digital twins, and cognitive wikis. src/rosclaw/mcp/onboarding/ handles installation and merge of MCP configuration into user workspaces. The tests/fixtures/fake_registry/ and tests/fixtures/hub_assets/ directories show the registry-first design.

13. User-facing products

src/rosclaw/dashboard/ serves operational views and first-boot UX. src/rosclaw/firstboot/ guides initial setup, telemetry, and workspace configuration. These are the human/operator surfaces over the runtime, not the core control loop itself.

14. Supporting libraries and experiments

src/rosclaw/skill_manager/, src/rosclaw/swarm/, src/rosclaw/control/, src/rosclaw/data/, and src/rosclaw/sdk_to_mcp/ are secondary modules for skill execution, multi-agent coordination, control primitives, buffering, and SDK-to-MCP compilation. They support the main runtime rather than defining it.

15. What to diagram as the main flow

The primary architecture diagram should show: intent enters via CLI/agent/MCP, body context is resolved, a provider selects a capability, the sandbox/firewall validates it, a runtime/driver executes it, Practice logs the trace, Sense reads state, Memory/Know retain evidence, How/Auto may intervene or improve, and Hub/Registry manage versioned assets and deployments.