Multi-project workspace for MuJoCo-based robot manipulation research. A curated set of focused libraries that compose into a full stack — from low-level joint control to high-level pick-and-place with behavior trees.
Built for the Geodude bimanual robot (dual UR5e + Robotiq 2F-140), but the core libraries (mj_manipulator, pycbirrt, tsr) are robot-agnostic and work with any MuJoCo arm.
git clone https://github.com/personalrobotics/robot-code
cd robot-code
./setup.sh # clones all repos, runs uv sync
uv run python -m geodude --demo recycling # headless
uv run python -m geodude --demo recycling --viser # browser viewer
uv run mjpython -m geodude --demo recycling --viewer # native MuJoCo viewerSee the geodude README for the full console guide, demos, and LLM chat.
┌─────────────────────────────────────────────────────────┐
│ geodude │
│ Bimanual robot: pickup/place primitives, behavior │
│ trees, Vention linear bases, interactive console │
├─────────────────────────────────────────────────────────┤
│ mj_manipulator │
│ Generic arm control: planning, execution, Cartesian │
│ control, grasping, collision checking │
├──────────────┬──────────────┬───────────────────────────┤
│ pycbirrt │ tsr │ mj_environment │
│ CBiRRT │ Task Space │ MuJoCo environment │
│ planner │ Regions │ wrapper + object registry│
├──────────────┴──────────────┼───────────────────────────┤
│ prl_assets + asset_manager │ geodude_assets │
│ Reusable objects (cans, │ Geodude MuJoCo models │
│ bins) + YAML loader │ (UR5e + Robotiq) │
└─────────────────────────────┴───────────────────────────┘
- ExecutionContext protocol — same code runs in kinematic simulation, physics simulation, and on real hardware.
SimContextfor MuJoCo,HardwareContext(via ROS 2) for real robots. - Everything goes through the context — no direct
mj_forwardordata.qposwrites during execution. Physics never freezes. - TSR-based grasping — grasp and placement poses defined as Task Space Regions. The planner handles IK internally.
- Behavior trees — manipulation primitives composed with py_trees. Recovery is built into the tree structure.
| Package | Description |
|---|---|
| geodude | Bimanual robot: high-level API, interactive console, demos, LLM chat |
| mj_manipulator | Generic arm control: planning, trajectory execution, Cartesian control |
| mj_manipulator_ros | WIP — ROS 2 bridge: HardwareContext, mock node |
| pycbirrt | CBiRRT motion planner with TSR constraints |
| tsr | Task Space Regions for grasp/place planning |
| mj_environment | MuJoCo environment wrapper with object registry |
| prl_assets | Reusable MuJoCo objects (cans, bins, spam cans, pop-tarts) |
| asset_manager | Loads object geometry from meta.yaml files |
| mj_viser | Web-based MuJoCo viewer built on Viser |
| geodude_assets | MuJoCo models for Geodude (UR5e + Robotiq 2F-140) |
# Run tests for a specific package
cd geodude && uv run pytest tests/ -v
# Run all tests across the workspace
uv run pytest */tests/ -vWork in progress. See geodude#91 for the architecture and setup guide.