BMO: a living desktop buddy with a Claude brain

Standalone React + Vite app where BMO lives in a little garden:
- Redrawn avatar (src/avatar) with depth, cartoon controls and expressive
  faces; original bmo-preview avatar and scenery kept in src/bmo
- Idle life: wandering, chatter, boredom, sleep, pokes, weather and
  time-of-day reactions
- Chat via a local Node server streaming Claude replies (Haiku by default),
  with live scene awareness and tools to change color, outfit, sky,
  weather, move and perform
- Side menu for API key, appearance, environment and chat log

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -0,0 +1,66 @@
+# BMO
+
+A little BMO that lives in a garden on your screen. It wanders, hums, gets bored,
+falls asleep when you leave it alone, reacts to the weather and the time of day,
+and talks back, powered by Claude.
+
+BMO's look lives in `src/avatar/Bmo.tsx`. It's a redraw built on the original
+[`bmo-preview`](https://github.com/PageZ948/bmo-preview) avatar. That original is kept unchanged in
+`src/bmo/` (copied from the `dream` project), and the new BMO still borrows its accessories, emotes,
+weather reactions, scenery and animation classes from there.
+
+## Run it
+
+```bash
+npm install
+npm run dev                # web on http://localhost:5180, brain on :4310
+```
+
+Then open the **⋮** menu (top right) and paste your Anthropic API key under
+**Brain**. The local server checks the key with Anthropic, then saves it to `.env`
+(gitignored, owner-only permissions) so it survives restarts. The browser only
+ever gets back a masked hint. You can also put `ANTHROPIC_API_KEY=...` in `.env`
+yourself (see `.env.example`).
+
+Without a key BMO still lives, wanders and reacts. It just tells you it can't
+reach its brain when you talk to it, and the ⋮ button shows an amber dot.
+
+Production-style:
+
+```bash
+npm run build && npm start # serves dist/ and /api from http://127.0.0.1:4310
+```
+
+## Things to try
+
+- **Talk to it** with the bar at the bottom. Replies stream into the speech bubble,
+  and BMO's face and emote follow the mood the model picks.
+- **Ask it to do things.** BMO knows its current color, outfit, sky, weather and
+  your local time, and it has tools to change them: "turn pink", "wear the top
+  hat", "make it rain", "make it night", "go stand on the left", "do a dance",
+  "take a nap".
+- **Poke it** by clicking BMO. Poke it too much and it gets grumpy.
+- **Call it over** by clicking the grass. BMO stays center stage, so it only moves a short way left or right.
+- **Leave it alone.** It gets bored after about a minute and falls asleep after about
+  2.5 minutes (sooner at night). Move the mouse to wake it.
+- **Wardrobe** (top right) changes colors and outfits, the accessory sets from
+  bmo-preview's personalities.
+- **Weather** changes by itself every few minutes, or you can set it from the menu.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/avatar/Bmo.tsx` | The BMO you see: body with depth, cartoon controls, expressive face (talk, grin, love, dizzy, sad, thinking, sleeping, grumpy) |
+| `src/bmo/` | Original bmo-preview avatar and scenery, copied unchanged; the scene and accessories still come from here |
+| `src/brain/useBmoBrain.ts` | BMO's behavior state machine: idle life, boredom, sleep, pokes, conversation, mapped to avatar props |
+| `src/brain/lines.ts` | Things BMO says on its own |
+| `src/chat/useChat.ts` | Streams replies from `/api/chat`; history is kept in localStorage |
+| `src/scene/World.tsx` | The garden: sky by time of day, terrain, flora, fog, fireflies, weather |
+| `server/index.ts` | Node server. Calls Claude with the API key kept server-side and streams the reply as server-sent events; only accepts POSTs from localhost pages |
+| `server/keystore.ts` | Saves the key from the menu into `.env` |
+| `server/persona.ts` | BMO's system prompt and mood tags |
+| `server/tools.ts` | BMO's tools (color, outfit, sky, weather, move, perform), input validation, and the live-scene note sent with each message |
+| `shared/scene.ts` | Option names and types shared by the page and the server |
+
+Model: `claude-haiku-5-5` at `effort: low` by default (cheap for testing). For the big brain, set `BMO_MODEL=claude-opus-5-5` in `.env`.