# ros-claw/rosclaw architecture

> Architecture diagram of the GitHub repository ros-claw/rosclaw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ros-claw/rosclaw
- Repository: https://github.com/ros-claw/rosclaw

## Overview

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.

Main entry points: [`src/rosclaw/provider`](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/provider) (Provider), [`src/rosclaw/sandbox`](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/sandbox) (Sandbox), [`src/rosclaw/body`](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/body) (Body), [`src/rosclaw/hub`](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/hub) (Hub)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control_plane["Control plane"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_main["Module main<br/>entrypoint<br/>[__main__.py]"]
  node_firstboot["First boot<br/>setup wizard"]
  node_dashboard["Dashboard<br/>operator UI"]
end

subgraph group_core_runtime["Core runtime"]
  node_core["Core runtime<br/>runtime backbone"]
  node_event_bus(("Event bus<br/>event backbone<br/>[event_bus.py]"))
end

subgraph group_embodiment["Embodiment"]
  node_body["Body<br/>embodiment model"]
  node_eurdf["EURDF<br/>embodiment schema"]
  node_e_urdf["E-URDF<br/>parser"]
  node_eurdf_zoo["Profile zoo<br/>robot profiles"]
end

subgraph group_intent_to_action["Intent to action"]
  node_provider["Provider<br/>capability router"]
  node_provider_runtimes["Provider runtimes<br/>execution backends"]
  node_provider_guard{{"Guard pipeline<br/>policy gate"}}
  node_sandbox["Sandbox<br/>action boundary"]
  node_firewall{{"Firewall<br/>safety gate"}}
  node_drivers["Drivers<br/>execution adapters"]
  node_connectors_ros["ROS connector<br/>ros bridge"]
  node_mcp["MCP<br/>tooling bridge"]
end

subgraph group_telemetry_learning["Telemetry and learning"]
  node_sense["Sense<br/>telemetry layer"]
  node_practice["Practice<br/>episode log"]
  node_memory[("Memory<br/>trace store")]
  node_know[("Know")]
  node_how{{"How<br/>recovery engine"}}
end

subgraph group_evolution["Evolution"]
  node_auto["Auto<br/>evolution engine"]
  node_darwin["Darwin<br/>evaluation"]
end

subgraph group_distribution["Distribution"]
  node_hub[("Hub<br/>asset registry")]
  node_onboarding["Onboarding<br/>mcp install"]
  node_forge["Forge<br/>bundle compiler"]
end

node_cli -->|"bootstraps"| node_firstboot
node_cli -->|"opens"| node_dashboard
node_main -->|"dispatches"| node_cli
node_core -->|"hosts"| node_event_bus
node_body -->|"loads"| node_eurdf
node_body -->|"parses"| node_e_urdf
node_body -->|"profiles"| node_eurdf_zoo
node_provider -->|"filters"| node_provider_guard
node_provider -->|"routes to"| node_provider_runtimes
node_provider -->|"uses context"| node_body
node_sandbox -->|"enforces"| node_firewall
node_sandbox -->|"invokes"| node_provider
node_sandbox -->|"publishes"| node_event_bus
node_drivers -->|"bridges"| node_connectors_ros
node_drivers -->|"executes under"| node_sandbox
node_connectors_ros -->|"supplies caps"| node_provider
node_connectors_ros -->|"normalizes"| node_body
node_mcp -->|"exposes"| node_provider
node_mcp -->|"wraps"| node_sandbox
node_sense -->|"subscribes"| node_event_bus
node_practice -->|"records from"| node_sense
node_practice -->|"writes traces"| node_memory
node_memory -->|"feeds"| node_know
node_know -->|"provides evidence"| node_how
node_how -->|"intervenes"| node_sandbox
node_auto -->|"improves"| node_how
node_auto -->|"evaluates"| node_darwin
node_auto -->|"publishes"| node_hub
node_hub -->|"installs"| node_onboarding
node_forge -->|"packages for"| node_hub
node_dashboard -->|"shows state"| node_sense
node_firstboot -->|"configures"| node_hub

click node_cli "https://github.com/ros-claw/rosclaw/blob/main/src/rosclaw/cli.py"
click node_main "https://github.com/ros-claw/rosclaw/blob/main/src/rosclaw/__main__.py"
click node_firstboot "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/firstboot"
click node_dashboard "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/dashboard"
click node_core "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/core"
click node_event_bus "https://github.com/ros-claw/rosclaw/blob/main/src/rosclaw/core/event_bus.py"
click node_body "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/body"
click node_eurdf "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/eurdf"
click node_e_urdf "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/e_urdf"
click node_eurdf_zoo "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/eurdf_zoo"
click node_provider "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/provider"
click node_provider_runtimes "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/provider/runtimes"
click node_provider_guard "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/provider/guard"
click node_sandbox "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/sandbox"
click node_firewall "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/firewall"
click node_drivers "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/mcp_drivers"
click node_connectors_ros "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/connectors/ros"
click node_mcp "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/mcp"
click node_sense "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/sense"
click node_practice "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/practice"
click node_memory "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/memory"
click node_know "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/know"
click node_how "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/how"
click node_auto "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/auto"
click node_darwin "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/darwin"
click node_hub "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/hub"
click node_onboarding "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/mcp/onboarding"
click node_forge "https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/forge"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_main,node_firstboot,node_dashboard,node_hub,node_onboarding,node_forge toneBlue
class node_core,node_event_bus toneAmber
class node_body,node_eurdf,node_e_urdf,node_eurdf_zoo toneMint
class node_provider,node_provider_runtimes,node_provider_guard,node_sandbox,node_firewall,node_drivers,node_connectors_ros,node_mcp toneRose
class node_sense,node_practice,node_memory,node_know,node_how toneIndigo
class node_auto,node_darwin toneTeal
```

## Components

### Control plane

Entry points, bootstrapping, and operator surfaces.

- [CLI](https://github.com/ros-claw/rosclaw/blob/main/src/rosclaw/cli.py): entrypoint · Main command-line entry for ROSClaw. · `src/rosclaw/cli.py`
- [Module main](https://github.com/ros-claw/rosclaw/blob/main/src/rosclaw/__main__.py): entrypoint · Python module entrypoint. · `src/rosclaw/__main__.py`
- [First boot](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/firstboot): setup wizard · Initial workspace setup, telemetry, and onboarding. · `src/rosclaw/firstboot`
- [Dashboard](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/dashboard): operator UI · Operational and first-boot user interface. · `src/rosclaw/dashboard`

### Core runtime

Shared runtime backbone and event infrastructure.

- [Core runtime](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/core): runtime backbone · Lifecycle, async utilities, events, and runtime primitives. · `src/rosclaw/core`
- [Event bus](https://github.com/ros-claw/rosclaw/blob/main/src/rosclaw/core/event_bus.py): event backbone · Central pub/sub boundary for runtime coordination. · `src/rosclaw/core/event_bus.py`

### Embodiment

Robot body models, embodiment compilation, and capability definitions.

- [Body](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/body): embodiment model · Robot body registry, compatibility, and safety metadata. · `src/rosclaw/body`
- [EURDF](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/eurdf): embodiment schema · Embodiment description loading and registry support. · `src/rosclaw/eurdf`
- [E-URDF](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/e_urdf): parser · Parser for extended robot descriptions. · `src/rosclaw/e_urdf`
- [Profile zoo](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/eurdf_zoo): robot profiles · Concrete robot profiles and simulation assets. · `src/rosclaw/eurdf_zoo`

### Intent to action

Capability routing, guards, sandboxing, and execution adapters.

- [Provider](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/provider): capability router · Intent routing boundary with guards and runtime adapters. · `src/rosclaw/provider`
- [Provider runtimes](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/provider/runtimes): execution backends · Python, HTTP, and ROS 2 runtime targets. · `src/rosclaw/provider/runtimes`
- [Guard pipeline](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/provider/guard): policy gate · Schema and action guards before capability execution. · `src/rosclaw/provider/guard`
- [Sandbox](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/sandbox): action boundary · Execution wrapper that mediates unsafe actions. · `src/rosclaw/sandbox`
- [Firewall](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/firewall): safety gate · Allows, modifies, blocks, or confirms actions. · `src/rosclaw/firewall`
- [Drivers](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/mcp_drivers): execution adapters · ROS 2, serial, MuJoCo, and ManiSkill bridges. · `src/rosclaw/mcp_drivers`
- [ROS connector](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/connectors/ros): ros bridge · ROS discovery, normalization, compiler, and transport integration. · `src/rosclaw/connectors/ros`
- [MCP](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/mcp): tooling bridge · MCP server, schemas, tools, and adapters. · `src/rosclaw/mcp`

### Telemetry and learning

Sensing, practice logs, memory, knowledge, and recovery.

- [Sense](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/sense): telemetry layer · Collectors, estimators, and runtime health evaluation. · `src/rosclaw/sense`
- [Practice](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/practice): episode log · Episode recording and timeline persistence. · `src/rosclaw/practice`
- [Memory](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/memory): trace store · Persistent search and retrieval over experience traces. · `src/rosclaw/memory`
- [Know](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/know): knowledge graph · Structured task, embodiment, verifier, and evidence knowledge. · `src/rosclaw/know`
- [How](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/how): recovery engine · Intervention and self-healing logic based on evidence and rules. · `src/rosclaw/how`

### Evolution

Auto-improvement, validation, and benchmark systems.

- [Auto](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/auto): evolution engine · Diagnosis, patch validation, promotion, and rollback. · `src/rosclaw/auto`
- [Darwin](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/darwin): evaluation · Scenarios, metrics, and benchmark runner integration. · `src/rosclaw/darwin`

### Distribution

Asset registry, onboarding, and packaging flows.

- [Hub](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/hub): asset registry · Versioned asset publishing, resolving, verification, and install. · `src/rosclaw/hub`
- [Onboarding](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/mcp/onboarding): mcp install · Workspace merge and MCP configuration onboarding. · `src/rosclaw/mcp/onboarding`
- [Forge](https://github.com/ros-claw/rosclaw/tree/main/src/rosclaw/forge): bundle compiler · Packaging utilities for compiled bundles. · `src/rosclaw/forge`

## Connections

- CLI → First boot: bootstraps · CLI launches setup and workspace initialization.
- CLI → Dashboard: opens · CLI connects operators to the dashboard surface.
- Module main → CLI: dispatches · Module entrypoint forwards to the CLI.
- Core runtime → Event bus: hosts · Core runtime provides the event bus and lifecycle primitives.
- Body → EURDF: loads · Body layer resolves embodiment definitions through EURDF.
- Body → E-URDF: parses · Body tooling consumes extended URDF descriptions.
- Body → Profile zoo: profiles · Robot profiles and assets feed the body registry.
- Provider → Guard pipeline: filters · Capability requests must pass guard checks.
- Provider → Provider runtimes: routes to · Validated requests are dispatched to runtimes.
- Provider → Body: uses context · Capability selection depends on embodiment context.
- Sandbox → Firewall: enforces · Sandbox execution is mediated by firewall policy.
- Sandbox → Provider: invokes · Sandboxed actions originate from provider-selected capabilities.
- Sandbox → Event bus: publishes · Sandbox emits execution events into the core bus.
- Drivers → ROS connector: bridges · Drivers bridge runtime execution to ROS environments and simulators.
- Drivers → Sandbox: executes under · Hardware and simulator actions run within the sandbox boundary.
- ROS connector → Provider: supplies caps · ROS discovery and manifests feed capability exposure.
- ROS connector → Body: normalizes · ROS graph information informs body and capability mapping.
- MCP → Provider: exposes · MCP surfaces capabilities to external clients.
- MCP → Sandbox: wraps · MCP tools route through the safety boundary.
- Sense → Event bus: subscribes · Telemetry and estimators consume runtime events.
- Practice → Sense: records from · Practice captures episodes from sensed state and events.
- Practice → Memory: writes traces · Episodes are persisted for later retrieval.
- Memory → Know: feeds · Stored traces inform structured knowledge artifacts.
- Know → How: provides evidence · Knowledge artifacts support recovery and intervention.
- How → Sandbox: intervenes · Recovery logic can redirect or constrain execution.
- Auto → How: improves · Auto systems use failures and interventions to drive patch evolution.
- Auto → Darwin: evaluates · Benchmarks and scenarios validate candidate changes.
- Auto → Hub: publishes · Promoted assets are distributed through the hub.
- Hub → Onboarding: installs · Registry assets are merged into user workspaces.
- Forge → Hub: packages for · Bundling supports hub-distributed assets.
- Dashboard → Sense: shows state · Operator views present health and readiness signals.
- First boot → Hub: configures · Initial setup prepares registry and asset access.