CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a meta-development environment for building Reachy Mini robot applications using Claude Code. It is not an app itself — it contains configuration, rules, skills, and documentation that teach Claude Code how to develop Reachy Mini apps. The robot is a small open-source desktop humanoid with a 6-DOF head (Stewart platform), body rotation, and two antenna motors.

Repository Layout

• .claude/rules.md — Code style, SDK patterns, safety guidelines
• .claude/agents.md — AI agent behavior guide (always-on, read first)
• .claude/agentic-folders.md — Agentic-folders documentation system (AGENT.md per folder)
• .claude/guidelines/skills/reachy-mini-app/ — 13 skill files covering SDK reference, app creation, control loops, motion, AI integration, debugging, testing, REST API, etc.
• documentation/ — User-facing guides: quickstart, installation, cheat sheet, workflow
• main.py — Example emotion demo app showing canonical app structure

Key Development Commands

# Create a new app
reachy-mini-app-assistant create

# Install app in dev mode
pip install -e ./your_app_name

# Start the daemon (real hardware)
reachy-mini-daemon

# Start the daemon (simulation, no robot needed)
python -m reachy_mini.daemon.app.main --sim --headless

# Dashboard
open http://127.0.0.1:8000

# Quick test an app (30-second local run)
python your_app_name/main.py --test

# Validate before publishing
reachy-mini-app-assistant check

# Publish to Hugging Face
reachy-mini-app-assistant publish
reachy-mini-app-assistant publish --official

# Code quality
black your_app/ --line-length 100
ruff check your_app/
ruff check your_app/ --fix
pytest

Architecture & Conventions

App Structure Pattern

All apps inherit from ReachyMiniApp and implement run(reachy_mini, stop_event). The stop_event must be checked frequently for graceful shutdown. Apps return the robot to neutral on exit.

class YourApp(ReachyMiniApp):
    custom_app_url: str | None = None  # Set if web UI exists

    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event):
        while not stop_event.is_set():
            # Main logic
            pass
        # Cleanup: return to neutral

Two Motion Methods

• goto_target() — Smooth interpolation for gestures (default, min 0.5s duration). Interpolation methods: linear, minjerk (default), ease, cartoon.
• set_target() — Immediate position for real-time control loops (10Hz+, no interpolation).

SDK-First Rule

The Reachy Mini SDK is newer than AI training data. Before implementing any robot functionality, check the installed SDK source at .venv/lib/python3.10/site-packages/reachy_mini/ to avoid hallucinating nonexistent methods. Start with reachy_mini.py for available methods.

Agent Workflow

1. Check for agents.local.md first (user context and robot type)
2. Create plan.md before coding any app
3. Always use Python (JS-only apps are not discoverable)
4. Use reachy-mini-app-assistant create to scaffold new apps
5. Store session context in agents.local.md

Agentic-Folders System

Each meaningful folder can have an AGENT.md (template at .claude/AGENT-template.md). This file is the source of truth for that folder — read the closest one when starting work. Update it when folder structure, entry points, or commands change.

Code Style

• Python 3.8+, PEP 8, black (line length 100), ruff
• Type hints on all function parameters and return values
• Docstrings on all classes and public methods
• Conventional commits: feat:, fix:, docs:, etc.

Safety Limits

Joint	Range
Head pitch/roll	[-40, +40]°
Head yaw	[-180, +180]°
Body yaw	[-160, +160]°
Yaw delta (head − body)	Max 65°

SDK clamps values automatically. Always test in simulation first.

Hardware Variants

• Lite: USB-connected, full laptop compute, best for development
• Wireless: Onboard CM4, WiFi, limited compute/memory
• Simulation: No robot needed, uses Mujoco (pip install "reachy-mini[mujoco]")

Key Resources

• SDK source: https://github.com/pollen-robotics/reachy_mini
• Official apps: https://huggingface.co/spaces/pollen-robotics/Reachy_Mini_Apps
• Publishing guide: https://huggingface.co/blog/pollen-robotics/make-and-publish-your-reachy-mini-apps
• REST API docs (when daemon running): http://127.0.0.1:8000/docs

Read agents.md in this directory for full instructions on developing Reachy Mini applications.