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 📊
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
- Prerequisites
- Install
- Quick Start
- Commands
- Species
- Rarity Tiers
- Stats
- How It Works
- After Claude Code Updates
- Troubleshooting
- Uninstall
- Contributing
- License
Before installing, make sure you have:
- 🍎 macOS — required (uses
codesignfor binary re-signing) - 🐍 Python 3 — ships with macOS; verify with
python3 --version - 🤖 Claude Code — CLI version with the Buddy feature
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.
Press START on your evolution adventure:
- 🍄 Run
/buddy-evolve - 🎨 Design your buddy — pick species, rarity, emoji, name, personality, and stats
- ✨ Restart Claude Code — your new companion appears
The whole process takes about 60 seconds. Every choice is yours.
To revert anytime: /buddy-reset 🔄
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:
- 🧬 Species — Pick from 18 species (dragon, cat, axolotl, capybara, and 14 more)
- ⭐ Rarity — Choose a tier from legendary to common
- 🎭 Emoji — Any emoji to represent your buddy in the terminal
- ✏️ Name — Give your evolved buddy a name
- 💬 Personality — A sentence or two shown on the buddy card
- 📊 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.
🔄 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
🧪 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.
🔬 Advanced. Investigates the binary when anchor patterns break after a major Claude Code update. Searches for updated variable names and proposes code updates.
Most players will never need this — it's for when /test-patch reports failures.
Choose from 18 species during evolution:
| 🦆 duck | 🪿 goose | 🫠 blob | 🐱 cat |
| 🐲 dragon | 🐙 octopus | 🦉 owl | 🐧 penguin |
| 🐢 turtle | 🐌 snail | 🦎 axolotl | 👻 ghost |
| 🤖 robot | 🍄 mushroom | 🌵 cactus | 🐇 rabbit |
| 🐖 chonk | 🦫 capybara |
Rarity determines how often your buddy reacts to your work — like a companion's chattiness slider:
| Tier | Reaction Rate | Vibe |
|---|---|---|
| ✨ Legendary | 50% | Main character energy — reacts to everything |
| 💎 Epic | 35% | Hype beast — always in the mix |
| 🔮 Rare | 25% | Solid sidekick energy |
| 🌿 Uncommon | 15% | Occasional words of wisdom |
| 🪨 Common | 5% | The strong, silent type |
Five RPG stats, each ranging 0–99. Choose a preset during evolution or min-max to your heart's content:
| Stat | What It Does |
|---|---|
| 🐛 DEBUGGING | How tenaciously your buddy hunts bugs |
| ⏳ PATIENCE | Tolerance for long builds and slow tests |
| 🌀 CHAOS | Tendency toward creative mischief |
| 🧠 WISDOM | Depth of sage advice offered |
| 😏 SNARK | Sharpness of witty commentary |
Presets:
- 💪 All Maxed — 99 across the board, the power fantasy
- 🌀 Chaos Gremlin — 99 CHAOS, low everything else
- 🧘 Zen Master — 99 WISDOM and PATIENCE, inner peace
- 🎛️ Custom — Set each stat yourself, RPG style
The plugin patches the Claude Code binary (a Bun-compiled Mach-O executable) to swap your buddy's species, rarity, shiny status, and ASCII art. Name and personality are written to ~/.claude.json separately.
The important bits:
- 📏 All patches maintain exact byte length — like fitting new sprites into the same cartridge
- 🔍 Patterns are located by anchor searching, not hardcoded offsets
- 🧬 Multi-version support — the script stores multiple known variable maps and auto-detects which one matches the current binary at runtime. No manual updates needed when switching between supported versions.
- 💾 The original binary is backed up automatically before any changes — your save file is safe
- 🔏 After patching, the binary is re-signed with
codesign - ✅ Post-patch binary verification — runs
--versionafter patching; auto-restores from backup if the binary is corrupted - 🔄 Everything is fully reversible with
/buddy-reset
Claude Code auto-updates replace the patched binary, which reverts your buddy to default. Don't panic — your buddy remembers who they are.
To re-evolve:
/buddy-evolve
Your preferences are saved, so re-application is quick — just confirm your choices and go. Like re-equipping your gear after a save reload. ⚔️
The patching script auto-detects which binary version you're running and uses the matching variable map — no manual intervention needed for supported versions.
If patching fails after an update:
- 🧪 Run
/test-patchto check which anchors broke - 🔬 If failures found, run
/update-species-mapor file an issue - 💾 Your backup is safe and unaffected by updates
🔄 My buddy didn't change after evolving
You need to restart Claude Code after evolution — like rebooting after installing a mod:
pkill -f claude && claude🔏 codesign failed
Make sure you're on macOS. Verify the binary path resolves:
readlink ~/.local/bin/claudeIf the path is broken, Claude Code may need to be reinstalled.
⚠️ Pattern not found / anchor warnings
Claude Code updated and the binary structure changed. Run /test-patch to check compatibility, then /update-species-map if needed.
Your existing buddy still works — only re-customization is affected until patterns are updated.
🔁 I want to change my buddy again
Just run /buddy-evolve again! No need to reset first — the script is re-runnable. Redesign as many times as you want.
🐧 Can I use this on Linux or Windows?
Not currently. The plugin requires macOS codesign for binary re-signing after patching.
🛡️ Is this safe? Can it break Claude Code?
The original binary is always backed up before changes — like a save state before the boss fight. Run /buddy reset to restore it at any time. In the worst case, reinstalling Claude Code gives you a fresh binary.
If you've customized your buddy, reset first:
/buddy-reset
Then remove the plugin (inside Claude Code):
/plugin uninstall buddy-evolver@soul-craft
If you skip the reset, your customized buddy remains until the next Claude Code auto-update replaces the binary.
Issues and PRs welcome at github.com/Soul-Craft/buddy-evolver.
If you modify scripts/patch-buddy.py, every binary patch must produce output identical in byte length to the original — like fitting new sprites into the same ROM. Test with --dry-run before committing.