buddy-evolution

buddy-evolution

Companion progression system for Claude Code. Your buddy has moods, personality, evolves through 36 unique forms, earns items, and speaks in character.

Born from the community response to Anthropic's /buddy April Fools feature (#41867 — 116+ upvotes). The ASCII pet may be temporary, but the companion lives on.

What makes this different

Most buddy tools just track XP. Ours builds a living character:

• Emotional state — mood decays with inactivity, recovers when you work. Leave for 3 days? Your buddy gets lonely.
• Personality voice — 12 distinct personalities shape how your buddy greets you, reacts to achievements, and comments in journals
• Evolution forms — 36 unique ASCII art designs. A Scholar Turtle looks nothing like a Chaos Dragon.
• Universal activity tracking — not just coding. Research, PM, creative work all count.

Features

Character System (v0.2.0)

• 10 moods — happy, tired, lonely, grumpy, excited, curious, proud, zen, mischievous, content
• 12 personality voices — sarcastic, cheerful, stoic, curious, dramatic, zen, chaotic, scholarly, protective, trickster, nostalgic, philosophical
• Energy & affection — decay over time (2/h, 0.5/h), recover with sessions and interactions
• Speech bubbles — personality-voiced reactions to milestones
• Relationship stages — stranger → acquaintance → companion → partner → soulmate (by session count)

Progression

• 30 achievements across 4 categories (coding, research, PM, creative)
• 5 tiers with 4 sublevels each = 20 levels (Hatchling → Ascended)
• Stat growth — DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK with diminishing returns
• Streak multipliers — consecutive days boost XP
• Per-project stats — XP and sessions tracked per directory

Evolution

• 6 species with full evolution trees
• 36 unique forms — each with custom ASCII art and personality modifiers
• Branching paths — your choices shape your buddy's character permanently

Species	Level 5	Level 10
Turtle	Scholar / Trickster	Ancient Sage, Librarian / Jester, Phantom
Cat	Hunter / Napper	Panther, Lynx / Sphinx, Cheshire
Dragon	Guardian / Inferno	Elder Wyrm, Crystal Drake / Chaos Dragon, Storm Wyrm
Owl	Professor / Nightwatch	Archmage, Scribe / Ghost Owl, Sentinel
Robot	Optimizer / Companion	Quantum Core, Architect Bot / Buddy Bot, Medic Bot
Ghost	Poltergeist / Specter	Wraith, Tinkerer Ghost / Banshee, Shade

Items & Inventory

• 15 unlockable items — hats, accessories, backgrounds, emotes
• Earned through achievements (Party Hat for first commit, Detective Hat for bug squashing, etc.)

Visual

• ANSI 256-color — rarity determines color complexity (gray → rainbow gradient)
• Mood expressions — eyes and emotes change with mood (^ ^ happy, > > grumpy, - - tired)
• Animation frames — blink, movement, sleep cycles (3-second refresh)
• Interactive TUI — curses-based companion with menu system

Commands

Command	What it does
/buddy-pet	Pet your buddy — affection +10, personality reaction
/buddy-talk	Talk — contextual response in character
/buddy-evolve	Choose evolution path at tier milestones

Quick Start

1. Clone & build

git clone https://github.com/Hegemon78/buddy-evolution
cd buddy-evolution && pnpm install && pnpm build

2. Add hooks to ~/.claude/settings.json

Add inside the "hooks" object:

"PostToolUse": [
  {
    "hooks": [{
      "type": "command",
      "command": "node \"/path/to/buddy-evolution/packages/plugin/dist/hooks/post-tool-use.js\"",
      "timeout": 5
    }]
  }
],
"SessionEnd": [
  {
    "hooks": [{
      "type": "command",
      "command": "node \"/path/to/buddy-evolution/packages/plugin/dist/hooks/session-end.js\"",
      "timeout": 30
    }]
  }
],
"SessionStart": [
  {
    "hooks": [{
      "type": "command",
      "command": "node \"/path/to/buddy-evolution/packages/plugin/dist/hooks/session-start.js\"",
      "timeout": 5
    }]
  }
]

Replace /path/to/buddy-evolution with your actual path.

3. Start a Claude Code session

The plugin detects your companion automatically. You'll see a personality-driven greeting with ASCII art, mood, and stats.

4. Companion apps (optional)

# Animated dashboard (refreshes every 3s)
bash companion-app.sh

# Interactive TUI with menu (M=menu, C=characters, I=inventory, Q=quit)
python3 companion-interactive.py

How It Works