reachy-mini

Reachy Mini Claude Code Plugin

Automatic emotion-based movements for Reachy Mini robot during Claude Code conversations

---

Overview

This Claude Code plugin enables Reachy Mini to automatically perform emotion-based movements synchronized with Claude's responses, creating natural multimodal communication without requiring explicit commands.

Key Features:

• 🎭 82 emotion moves from Pollen Robotics' official library
• 🎵 TTS synchronization - Continuous movements match speech duration
• 🎨 8 mood categories - Automatic emotion selection based on conversational context
• 🔄 Two modes - Single emotions or continuous mood loops
• 🤖 Invisible markers - HTML comments trigger movements without cluttering output

---

Table of Contents

• Installation
• Quick Start
• How It Works
• Usage Modes
  • Single Move Mode
  • Continuous Mood Mode
• Available Emotions
• Mood Categories
• Integration with ElevenLabs TTS
• Technical Architecture
• Configuration
• Troubleshooting
• Contributing
• License

---

Installation

Prerequisites

1. Reachy Mini robot with daemon running:

   mjpython -m reachy_mini.daemon.app.main --fastapi-port 8100
   

2. Claude Code installed and configured

3. Python 3.8+ with requests library:

   pip install requests
   

Install Plugin

1. Clone this repository into your Claude Code plugins directory:

   cd ~/.claude/plugins
   git clone https://github.com/LAURA-agent/reachy-mini-plugin.git reachy-mini
   

2. Restart Claude Code to load the plugin

3. Verify installation:

   # Plugin should appear in available plugins list
   ls ~/.claude/plugins/reachy-mini
   

---

Quick Start

Single Move Example

<!-- MOVE: thoughtful1 -->
Let me analyze this code carefully...

Result: Reachy performs a thoughtful gesture once

Continuous Mood Example

<!-- TTS: "The build passed! All tests are green and deployment is complete." -->
<!-- MOOD: celebratory -->
Build successful! All tests passing, zero errors, deployed in under 2 minutes.

Result: Reachy continuously performs celebratory emotions (success, proud, cheerful) until TTS finishes speaking

---

How It Works

The plugin uses Stop hooks to automatically detect and process movement markers in Claude's responses:

1. Claude generates response with embedded markers
2. Stop hook fires after response completes
3. Extractors parse markers from response text
4. API calls trigger movements on Reachy Mini daemon
5. Movements execute in sync with TTS (if using mood mode)

Marker Format

Single Move:

<!-- MOVE: emotion_name -->

Continuous Mood:

<!-- MOOD: mood_category -->

Markers are invisible in rendered output - they only appear in the raw response text.

---

Usage Modes

Single Move Mode

Use when: Short responses, specific emotional reactions, precise control

Command: /reachy-mini:move

Marker: <!-- MOVE: emotion_name -->

Behavior:

• Maximum 2 moves per response (for subtlety)
• Triggers specific emotions from the 82-emotion library
• No TTS synchronization - fires immediately
• Best for quick reactions and acknowledgments

Example:

<!-- MOVE: surprised1 -->
Found it! This callback is firing 15,000 times per second.

---

Continuous Mood Mode

Use when: Longer explanations, sustained presence, TTS-synchronized communication

Command: /reachy-mini:mood

Marker: <!-- MOOD: mood_category -->

Behavior:

• Continuously loops random emotions from selected mood
• Polls TTS server for playback status
• Stops automatically when TTS finishes (is_playing: false)
• Safety timeout: 60 seconds maximum
• Best for detailed responses and explanations

Example:

<!-- TTS: "Let me explain async patterns. Promises handle future values, async await makes them readable." -->
<!-- MOOD: thoughtful -->

Let me break down async patterns step by step:
- Promises represent future values
- Async/await makes them readable
- Proper error handling prevents silent failures

Result: Thoughtful emotions (thoughtful1, curious1, attentive1, etc.) play continuously during ~30 second TTS

---

Available Emotions

82 total emotions from Pollen Robotics library: