# 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

```bash
# 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.

```python
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.