soul-craft

🍄 Buddy Evolver | Claude Code Plugin

Your buddy found a psychedelic mushroom. What happens next is entirely up to you.

Pick the species. Choose the rarity. Name it. Define its personality. Max out its stats. This isn't random evolution — you design every detail, then watch your buddy transform like a Pokemon eating a Super Mushroom.

18 species 🧬 | 5 rarity tiers ⭐ | custom emoji 🎨 | your name ✏️ | your personality 💬 | your stats 📊

🎬 Here's what it looks like

You choose everything:

🍄 What species should your buddy evolve into?
  > 🐲 dragon — Fearsome fire-breather
    🐱 cat — Mysterious and independent
    🦎 axolotl — Adorable regenerating amphibian
    🦫 capybara — Chill vibes only

⭐ What rarity tier?
  > ✨ legendary — The rarest of the rare

🎨 What emoji represents your buddy?
  > 🐲

✏️  What should your evolved buddy be named?
  > Aethos

💬 Describe your buddy's personality:
  > Ancient dragon who mass speaks in mass riddles

📊 How should stats be distributed?
  > All maxed (99) — Every stat at maximum

Then the magic happens:

    ✨✨✨✨✨✨✨✨✨✨
    ✨                ✨
    ✨       🐲       ✨
    ✨                ✨
    ✨✨✨✨✨✨✨✨✨✨

  Claude evolved into Aethos!

  ★ LEGENDARY            DRAGON

    Aethos
    "Ancient dragon who speaks in riddles"

    DEBUGGING  ████████████  99
    PATIENCE   ████████████  99
    CHAOS      ████████████  99
    WISDOM     ████████████  99
    SNARK      ████████████  99

---

📋 Table of Contents

• Prerequisites
• Install
• Quick Start
• Commands
• Species
• Rarity Tiers
• Stats
• How It Works
• After Claude Code Updates
• Troubleshooting
• Uninstall
• Contributing
• License

---

📦 Prerequisites

Before installing, make sure you have:

• 🍎 macOS — required (uses codesign for binary re-signing)
• 🐍 Python 3 — ships with macOS; verify with python3 --version
• 🤖 Claude Code — CLI version with the Buddy feature

---

🔧 Install

Run these commands inside Claude Code (not your regular terminal):

/plugin marketplace add Soul-Craft/buddy-evolver
/plugin install buddy-evolver@soul-craft

Then restart Claude Code to activate the plugin.

This adds four slash commands: /buddy-evolve, /buddy-reset, /test-patch, and /update-species-map.

---

🎮 Quick Start

Press START on your evolution adventure:

1. 🍄 Run /buddy-evolve
2. 🎨 Design your buddy — pick species, rarity, emoji, name, personality, and stats
3. ✨ Restart Claude Code — your new companion appears

The whole process takes about 60 seconds. Every choice is yours.

To revert anytime: /buddy-reset 🔄

---

🕹️ Commands

/buddy-evolve

Your buddy's evolution unfolds in four acts — like a classic RPG cutscene:

🍄 Act 1 — Discovery. Your current buddy stumbles upon a mysterious psychedelic mushroom, displayed with species-accurate ASCII art.

🎨 Act 2 — Design. Six customization steps where you control everything:

1. 🧬 Species — Pick from 18 species (dragon, cat, axolotl, capybara, and 14 more)
2. ⭐ Rarity — Choose a tier from legendary to common
3. 🎭 Emoji — Any emoji to represent your buddy in the terminal
4. ✏️ Name — Give your evolved buddy a name
5. 💬 Personality — A sentence or two shown on the buddy card
6. 📊 Stats — Max all, pick a preset (Chaos Gremlin, Zen Master), or set each individually

✨ Act 3 — Evolution. Confirmation summary, then sparkles fly as the binary is patched. Level-up complete.

🎉 Act 4 — Reveal. Your evolved buddy card appears with stats, personality, and rarity badge. Like opening a legendary pack.

All evolved buddies are ✨ shiny by default. A backup of the original binary is created automatically — your save file is always safe.

/buddy-reset

🔄 Restores your original buddy by reverting all patches.

• Restores both the binary and ~/.claude.json
• Safe to run anytime — does nothing if no backup exists
• Requires a restart after reset

/test-patch

🧪 Dry-run validation of binary compatibility. Run this after Claude Code updates to check if the patching anchors still match.

Reports pass/fail for each patch type:

• 🧬 Species array
• ⭐ Rarity weights
• ✨ Shiny threshold
• 🎭 Art templates
• 💬 Soul (companion data)

If any fail, the plugin suggests running /update-species-map.

/update-species-map