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