# Building a Chess Emotions App with Claude Code

This document captures how we built a chess app where Reachy Mini reacts emotionally to your moves - from idea to working prototype in a single conversation.

---

## The Initial Idea

**User:**
> I want to create a funny app where I play chess on my browser vs stockfish and reachy mini plays emotions based on how good my move is.

**Claude:** Read the Reachy Mini development guide, checked the emotions library (70+ emotions available!), and created a plan:

- Chess runs entirely in browser (chess.js + chessboard.js + Stockfish WASM)
- Emotions triggered via REST API calls to Reachy daemon
- Asked clarifying questions about allegiance, difficulty, reaction frequency

---

## Iteration 1: Basic Setup

**User:** Answered the questions in `plan.md`:
- Reachy roots for Stockfish (funnier!)
- Adjustable ELO slider
- React to every move
- Sound effects (built into emotions)

**Claude:** Generated the complete app structure:
- `static/index.html` - Chess UI with evaluation bar
- `static/style.css` - Dark theme styling
- `static/main.js` - Chess logic + Stockfish + emotion triggers
- `main.py` - Minimal Python wrapper

---

## Iteration 2: Fixing Issues

**User:**
> The robot plays emotions but I can't play chess after clicking on new game? I see no pieces

**Claude:** Fixed initialization timing - wrapped in `$(document).ready()` and changed piece image URL to more reliable source.

---

## Iteration 3: Board Size + Stockfish Not Responding

**User:**
> The board should be much bigger, 2 or 3 times bigger. Also after the first move it's stuck on "Stockfish is thinking..."

**Claude:**
- Increased board from 400px to 700px
- Fixed Stockfish WASM loading

**User:**
> Also I had this error: Erreur de sécurité : le contenu situé à http://127.0.0.1:8042/ ne peut pas charger de données...

**Claude:** Downloaded Stockfish locally to avoid CORS issues:
```bash
curl -sL "https://unpkg.com/stockfish.js@10.0.2/stockfish.js" -o static/stockfish.js
```

---

## Iteration 4: Gameplay Tuning

**User:**
> - Could stockfish play faster?
> - Emotions only when the human plays, not when the AI plays
> - Reachy should root for the human. Happy/positives emotions when a good move is done, negatives when it's bad. Add much more variety than currently

**Claude:**
- Reduced search depth from 15 to 8
- Removed emotion triggers after Stockfish moves
- Flipped emotion logic (Reachy now cheers for human!)
- Expanded emotion pools from ~4 to ~15 emotions per category

**Emotion mapping:**
| Move Quality | Emotions |
|--------------|----------|
| Brilliant | dances, celebrations, amazement (15 options) |
| Good | yes, proud, understanding (11 options) |
| Neutral | attentive, thoughtful, curious (8 options) |
| Mistake | oops, confused, displeased (12 options) |
| Blunder | sad, frustrated, rage, fear (15 options) |

---

## Iteration 5: Timing + Undo Button

**User:**
> I think the robot plays emotions when the AI plays no? Let's add a "cancel move" button. And now stockfish plays instant, let's find an inbetween, maybe depth 11?

**Claude:**
- Added 800ms delay between emotion trigger and Stockfish's move appearing
- Added "Undo Move" button (undoes both your move and Stockfish's response)
- Set depth to 11

**User:**
> Let's make it so the move of the AI appears after 3 seconds min

**Claude:** Added minimum 3-second delay from human move to AI response, giving Reachy time to fully express the emotion.

---

## Iteration 6: Eval Accuracy + Delta Calculation

**User:**
> You sure the evaluation is accurate and in the correct direction? I just had a negative value when white was clearly better and vice versa. Also let's consider the delta of eval between the state after the human played vs the state vs the last time the human played.

**Claude:** Fixed two issues:

1. **Eval direction** - Created `scoreFromWhitePerspective()` to properly convert Stockfish scores (always from side-to-move perspective) to White's perspective.

2. **Delta calculation** - Now compares eval after current move vs eval after previous move. This captures Stockfish blunders too! If AI blunders, the positive swing shows up when you play your next move.

---

## Final Result

A fully working chess app where:
- You play chess against Stockfish in the browser
- Adjustable difficulty (ELO 800-2800)
- Reachy Mini emotionally reacts to your moves
- 70+ different emotions with variety
- Undo button to take back moves
- Evaluation bar shows position advantage
- 3-second minimum reaction time for dramatic effect

**To run:**
```bash
cd chess_emotions_app
python -m chess_emotions_app.main
# Open http://localhost:8042/static/index.html
```

---

## Key Takeaways

1. **Iterative development works** - Started with basic idea, refined through feedback
2. **Quick fixes** - CORS issues, timing bugs, UI sizing all fixed in minutes
3. **Domain knowledge built-in** - Claude knew about Reachy's REST API, emotions library, app structure
4. **No boilerplate** - Used `reachy-mini-app-assistant create` to scaffold the app

**Total time:** ~20 minutes of conversation
**Lines of code:** ~400 (JS) + ~200 (CSS) + ~30 (Python)
**Result:** A fun, polished demo app ready to show off!