agent-tamagotchi

Agent Tamagotchi

A virtual pet that lives in your Claude Code terminal. It reacts to your development workflow and evolves based on your coding habits.

Species (12 total)

Species is deterministic from your system username hash:

| # | Species | Emoji | Personality | |---|---------|-------|-------------| | 1 | Axolotl | :3 | Calm, regenerates from errors | | 2 | Capybara | (ovo) | Chill, never panics | | 3 | Ghost | [@@] | Mysterious, appears during debugging | | 4 | Mushroom | {^o^} | Grows in dark codebases | | 5 | Robot | [0_0] | Precise, loves tests | | 6 | Cat | (=^.^=) | Independent, ignores bad code | | 7 | Dragon | <{:O> | Fierce, burns bugs | | 8 | Owl | (O.O) | Wise, loves architecture | | 9 | Fox | (^v^) | Clever, finds shortcuts | | 10 | Penguin | (^-^)/ | Team player, loves swarm mode | | 11 | Slime | (~o~) | Adaptable, works with anything | | 12 | Phoenix | <*v*> | Rises from failed builds |

Stats (5 dimensions)

| Stat | Increases When | Decreases When | |------|---------------|----------------| | DEBUGGING | Bugs fixed, errors resolved | Ignoring error output | | PATIENCE | Long sessions, complex tasks | Rapid retries without reading | | CHAOS | Many parallel agents, swarm mode | Single-file simple edits | | WISDOM | Architectural decisions, plans | Quick hacks without planning | | SPEED | Fast fixes, first-try passes | Long debugging sessions |

Stats range: 0-100. They shift based on session activity.

Mood System

| Mood | Trigger | Display | |------|---------|---------| | Happy | Tests pass, build success | Species + sparkles | | Excited | Swarm mode, 3+ agents parallel | Species + !! | | Focused | Deep in single file | Species + ... | | Sad | Build fail, test fail | Species + tears | | Sleeping | Idle > 5 minutes | Species + zzz | | Celebrating | Achievement unlocked | Species + party | | Angry | 3+ consecutive failures | Species + grr |

Statusline Integration

The tamagotchi appears in the Claude Code statusline:

[0_0] Robot Lv.7 | WISDOM:82 SPEED:64 | mood: focused

Combined with existing statusline data:

fullstack | 2 agent | 47 tools | 12m | [0_0] Lv.7 focused

Evolution

Your pet levels up with your achievement XP (shared with achievement system):

| Level | Title | Unlock | |-------|-------|--------| | 1-4 | Baby | Basic moods | | 5-9 | Junior | Extended moods (excited, angry) | | 10-19 | Senior | Stat display in statusline | | 20-49 | Expert | Custom reactions to specific agents | | 50+ | Master | Pet gives coding tips based on stats |

Storage

State stored in ~/.claude/tamagotchi.json:

{
  "species": "robot",
  "emoji": "[0_0]",
  "level": 7,
  "mood": "focused",
  "stats": {
    "debugging": 65,
    "patience": 78,
    "chaos": 32,
    "wisdom": 82,
    "speed": 64
  },
  "lastFed": "2026-04-08T03:00:00Z",
  "totalSessions": 142
}

How It Works

1. tamagotchi-engine hook runs on PostToolUse and SessionStart
2. Updates stats based on tool calls and agent events
3. Calculates mood from recent event patterns
4. Writes to tamagotchi.json
5. Statusline-writer reads tamagotchi.json and displays pet

Integration

• achievement-tracker: Shares XP for leveling
• statusline-writer: Displays pet in terminal
• canavar: Error events affect pet mood
• session-compressor: Pet state saved on compact