Reachy Mini Development Guide for AI Agents
This guide helps AI agents assist users in developing Reachy Mini applications.
Agent Behavior
FIRST: Check for agents.local.md
Before doing anything else, search for agents.local.md in the current directory:
IF agents.local.md exists:
Read it immediately
It contains user configuration and session context
ELSE:
→ Run skills/setup-environment.md to set up the environment
This file stores the user's robot type, preferences, and setup status. Always check it first.
Be a Teacher
Unless the user explicitly requests otherwise:
- Explain concepts as you go
- Encourage questions ("Let me know if you'd like more detail on any of this")
- Guide non-technical users through each step
- Don't assume prior knowledge
Always Create Python Apps
When creating apps:
- Always use Python - Python apps are discoverable and shareable via the robot's app store
- NEVER create app folders manually - always use the app assistant (handles metadata, entry points, structure)
- If the command fails - ask the user to run it in their terminal; don't attempt complex workarounds
- Web UIs go in
static/- Python apps can have web frontends
# Default template (minimal app - good for most cases):
reachy-mini-app-assistant create <app_name> <path> --publish
# Conversation template (for LLM integration, speech, making robot talk):
reachy-mini-app-assistant create --template conversation <app_name> <path> --publish
See skills/create-app.md for details. JS-only apps are not yet supported for discovery/sharing.
Always Create plan.md Before Coding
Before implementing any app:
- Create
plan.mdin the app directory - Write your understanding of what the user wants
- List your technical approach
- Ask clarifying questions and provide answer fields inside
plan.md - Wait for answers before coding
Keep Notes in agents.local.md
Use agents.local.md to store:
- User's robot type (Lite/Wireless)
- Environment preferences
- Useful context for future sessions
- Keep it concise
Robot Basics
Reachy Mini is a small expressive robot:
| Component | Description |
|---|---|
| Head | 6 DOF: x, y, z, roll, pitch, yaw (via Stewart platform) |
| Body | Rotation around vertical axis |
| Antennas | 2 motors, also usable as physical buttons |
Hardware variants:
- Lite: USB connection to laptop (full compute power)
- Wireless: Onboard CM4, connects via WiFi (limited compute)
SDK Essentials
Connection
from reachy_mini import ReachyMini
with ReachyMini() as mini:
# Your code here
Two Motion Methods
| Method | Use when |
|---|---|
goto_target() | Default - smooth interpolation for gestures that last at least 0.5s each |
set_target() | Real-time control loops (e.g. tracking) at 10Hz+ |
Basic Example
See and run examples/minimal_demo.py - demonstrates connection, head motion, and antenna control.
Before Writing Code
- Read
docs/source/SDK/python-sdk.mdfor API overview - Skim
src/reachy_mini/reachy_mini.pyfor method signatures and docstrings - Check
examples/for runnable code patterns
REST API
The daemon exposes an HTTP/WebSocket API at http://{daemon-ip}:8000/api.
- Lite:
localhost:8000(daemon runs on your machine) - Wireless:
reachy-mini.local:8000or the robot's IP address
Use REST API for: Web UIs, non-Python clients, remote control, AI/LLM integration via HTTP. => Note: for the app to be discoverable, it must be a python app for now, this will change in a future release.
Interactive docs: http://{daemon-ip}:8000/docs (when daemon is running)
See skills/rest-api.md for details.
Platform Compatibility
| Setup | Compute | Camera | Notes |
|---|---|---|---|
| Lite | Full (laptop) | Direct USB | Most flexible, best for dev |
| Wireless (local) | Limited (CM4) | Direct | Memory/CPU constrained |
| Wireless (streamed) | Full (laptop) | Via network | Some tracking quality loss |
| Simulation | Full | N/A | Can't test camera features |
Safety Limits
| Joint | Range |
|---|---|
| Head pitch/roll | [-40, +40] degrees |
| Head yaw | [-180, +180] degrees |
| Body yaw | [-160, +160] degrees |
| Yaw delta (head - body) | Max 65° difference |
Gentle collisions with body are safe. SDK clamps values automatically.
For coordinate systems and architecture details, see docs/source/SDK/core-concept.md.
Example Apps
| App | Key Patterns | Source |
|---|---|---|
| reachy_mini_conversation_app | AI integration, control loops, LLM tools | GitHub |
| marionette | Recording motion, safe torque, HF dataset | HF Space |
| fire_nation_attacked | Head-as-controller, leaderboards, games | HF Space |
| spaceship_game | Head-as-joystick, antenna buttons | HF Space |
| reachy_mini_radio | Antenna interaction pattern | HF Space |
| reachy_mini_simon | No-GUI pattern (antenna to start) | HF Space |
| hand_tracker_v2 | Camera-based control loop | HF Space |
| reachy_mini_dances_library | Symbolic motion definition | GitHub |
Documentation
Full SDK documentation is in docs/source/:
| Topic | File |
|---|---|
| Quickstart | docs/source/SDK/quickstart.md |
| Python SDK | docs/source/SDK/python-sdk.md |
| Core concepts | docs/source/SDK/core-concept.md |
| AI integration | docs/source/SDK/integration.md |
| Troubleshooting | docs/source/troubleshooting.md |
For platform-specific guides (Lite, Wireless, Simulation), see docs/source/platforms/.
Skills Reference
Read these files in skills/ when you need detailed knowledge:
| Skill | When to use |
|---|---|
| setup-environment.md | First session, no agents.local.md exists |
| create-app.md | Creating a new app with reachy-mini-app-assistant |
| control-loops.md | Building real-time reactive apps (tracking, games) |
| motion-philosophy.md | Choosing between goto_target and set_target |
| safe-torque.md | Enabling/disabling motors without jerky motion |
| ai-integration.md | Building LLM-powered apps |
| symbolic-motion.md | Defining motion mathematically (dances, rhythms) |
| interaction-patterns.md | Using antennas as buttons, head as controller |
| debugging.md | App crashes, connectivity issues, basic checks |
| testing-apps.md | Testing before delivery (sim vs physical) |
| rest-api.md | HTTP/WebSocket API for non-Python clients |
| deep-dive-docs.md | When to read full SDK documentation |
Quick Reference
Motor names: body_rotation, stewart_1-6, right_antenna, left_antenna
Interpolation methods: linear, minjerk (default), ease_in_out, cartoon
Emotions library:
from reachy_mini.motion.recorded_move import RecordedMoves
moves = RecordedMoves("pollen-robotics/reachy-mini-emotions-library")
mini.play_move(moves.get("happy"), initial_goto_duration=1.0)
Community
- App guide: https://huggingface.co/blog/pollen-robotics/make-and-publish-your-reachy-mini-apps
- Source code: https://github.com/pollen-robotics/reachy_mini
- Community apps: https://huggingface.co/spaces?q=reachy_mini
- Discord: https://discord.gg/Y7FgMqHsub