# 🐾 Pimagotchi

Pimagotchi (π + たまごっち) — a tamagotchi virtual pet for [pi coding agent](https://github.com/badlogic/pi-mono). Your pet evolves based on how you code.

![Pimagotchi widget](assets/widget.png)

## Install

```bash
pi install npm:@studiosunnyfield/pimagotchi
```

## Features

- **18 animated species** — duck, cat, dragon, ghost, axolotl, capybara, and more (3 animation frames each)
- **Behavior-based evolution** — egg hatches at Lv.3 into a species based on your tool usage: bash warriors get dragons, careful readers get owls, 3am coders get ghosts
- **Rarity system** — common → legendary, more coding = better odds
- **Cosmetics** — 6 eye styles, 8 hats (unlocked by rarity), 1% shiny chance ✧
- **Animated widget** — idle fidgets, blinks, excited during streaming, hearts when petted
- **Persistent** — your pet follows you across sessions

## Usage

![Pimagotchi menu](assets/menu.png)

| Action | How |
|--------|-----|
| **Action menu** | `Ctrl+;` — overlay with arrow navigation |
| **Toggle widget** | `/pet` |
| **Rename** | `/pet <name>` |
| **Feed** | `/pet feed` |
| **Pet** | `/pet pet` |
| **Stats** | `/pet stats` |
| **Manual hatch** | `/pet hatch` (if Lv.3+) |

## Evolution

Your egg hatches into a species based on your coding patterns:

| Pattern | Species Pool |
|---------|-------------|
| Bash-heavy | 🐉 dragon, 🤖 robot, 🪿 goose |
| Edit/write-heavy | 🐱 cat, 🐰 rabbit, 🌵 cactus |
| Read-heavy | 🦉 owl, 🍄 mushroom, 🐢 turtle |
| Night coding | 👻 ghost, 🦎 axolotl |
| High tool count | 🐙 octopus, 🐌 snail |
| Balanced | 🫧 blob, 🦫 capybara, 🐤 duck, 🐧 penguin, 😺 chonk |

## Rarity

| Rarity | Base Odds | Hats Available |
|--------|-----------|---------------|
| ★ Common | 60% | none, beanie |
| ★★ Uncommon | 25% | + propeller |
| ★★★ Rare | 10% | + tophat, wizard |
| ★★★★ Epic | 4% | + crown, halo |
| ★★★★★ Legendary | 1% | + tinyduck |

More tool calls at hatch time = better rarity odds.

## Credits

Sprite art adapted from Claude Code's buddy system. Evolution and progression system original.