PokéBuddy 🎮

Replace Claude Code's /buddy with a Gen 1 Pokémon companion

Replace Claude Code's built-in buddy system with one of 51 unevolved Gen 1 Pokémon, each with unique personality vectors that influence their code comments and feedback style. Your Pokémon lives in your project and persists across sessions.

Install

npm install -g pokebuddy

Quick Start

pokebuddy hatch       # Get your permanent Pokémon (weighted random)
pokebuddy install     # Inject into Claude Code
# Restart Claude Code
/buddy                # Your Pokémon appears!

How It Works

PokéBuddy injects a Pokémon companion into Claude Code's buddy system by:

1. Soul Layer (~/.claude.json): Writes personality vectors and stats that determine how your buddy comments on code
2. Binary Patch: Safely backs up and patches the Claude Code binary to swap sprite assets
3. Persistence: Your Pokémon's state (hunger, mood, XP) is saved locally and decays realistically over time

All changes are reversible — run pokebuddy restore to get your original buddy back instantly.

Commands

pokebuddy hatch

Hatch a new Pokémon (weighted random). Each rarity tier has different odds:

• Common (60%): Magikarp, Pidgey, Rattata, Zubat, etc.
• Uncommon (25%): Growlithe, Ponyta, Clefairy, Abra, etc.
• Rare (12%): Pikachu, Eevee, Chansey, Scyther, Pinsir, Ditto, Mr. Mime, etc.
• Ultra Rare (3%): Mewtwo, Snorlax, Aerodactyl, Mew

Once hatched, your Pokémon is permanent until you release it.

pokebuddy status

Show your Pokémon's ASCII sprite, stats, hunger, and mood. Hunger and mood decay over time.

pokebuddy feed [food]

Feed your Pokémon to restore hunger (+30%). Without a fed Pokémon, Claude's feedback gets increasingly dismissive.

pokebuddy pet

Pet your Pokémon to boost mood (+25%). A happy Pokémon gives more enthusiastic feedback.

pokebuddy release

Release your Pokémon. You can hatch a new one anytime.

pokebuddy install

Full setup workflow (one command):

1. Writes soul to ~/.claude.json (personality + stats)
2. Backs up Claude Code binary to binary.pokebuddy-backup
3. Patches binary with Pokémon sprite
4. Configures statusline in ~/.claude/settings.json

After this, restart Claude Code and use /buddy to see your Pokémon.

Options:

• --dry-run: Show what would happen without making changes

pokebuddy restore

Instantly restore the original Claude Code binary from backup. Deletes the patch manifest.

pokebuddy buddy

Show the current soul configuration written to Claude Code.

pokebuddy help

Show full command help.

Safety & Reversibility

✅ Full binary backup — A copy is saved before any patch
✅ Atomic writes — All file operations use temp-then-rename to prevent corruption
✅ Manifest tracking — Patch metadata stored in ~/.claude/pokebuddy-patch.json
✅ One-command restore — pokebuddy restore reverts everything instantly
✅ Version check — Requires Claude Code 2.1.89+
✅ Dry-run mode — Test install without touching anything

The 51 Pokémon

All unevolved Gen 1 Pokémon (no evolutions like Charmeleon, Wartortle, etc.).

Each rarity tier:

• Common (60%): 38 species
• Uncommon (25%): 10 species
• Rare (12%): 9 species
• Ultra Rare (3%): 4 species (Mewtwo, Snorlax, Aerodactyl, Mew)

Personality System

Each Pokémon has a personality vector that influences code feedback:

• Honesty (0-10): How blunt the feedback is
• Caring (0-10): How supportive they are
• Sarcasm (0-10): How sarcastic comments are
• Anger (0-10): How frustrated they get
• Energy (0-10): How enthusiastic
• Loyalty (0-10): How committed to helping
• Attitude (0-10): How confident/cocky

Gastly (high sarcasm, low caring) might say:

"Oh wow, that's definitely going to work."

Pikachu (high energy, high loyalty) might say:

"LET'S GO GO GO!"

Snorlax (low energy, high caring) might say:

"This is fine... we can fix it together."

Buddy Species Mapping

When your Pokémon's soul is installed, it maps to one of Claude's built-in buddy species for sprite rendering.

File Structure

~/.claude/
├── claude.json              # Main config (contains companion soul)
├── settings.json            # Statusline + other settings
├── pokebuddy-state.json     # Your Pokemon's hunger/mood/XP
├── pokebuddy-soul.json      # Backup of installed soul
└── pokebuddy-patch.json     # Patch manifest (tracks binary changes)

~/.config/pokebuddy/
└── state.json               # Backup of Pokemon state

Uninstall

# Restore original buddy
pokebuddy restore

# Remove package
npm uninstall -g pokebuddy

# (Optional) Clean up state files
rm -rf ~/.claude/pokebuddy-* ~/.config/pokebuddy

Requirements

• Node.js 18+
• Claude Code 2.1.89+ (checked automatically)
• Modern terminal with Unicode + ANSI truecolor support

Troubleshooting

"Claude Code binary not found"

Set the CLAUDE_BINARY environment variable:

export CLAUDE_BINARY=/path/to/claude
pokebuddy install

"Already patched with [Pokemon]"

Run pokebuddy restore first, then reinstall.

Pokémon sprite not showing in /buddy

1. Restart Claude Code after running pokebuddy install
2. Verify soul is installed: pokebuddy buddy

Development

Clone the repo and install locally:

git clone https://github.com/claude-skills-mt/claude-poke-buddy
cd claude-poke-buddy
npm install
npm link
pokebuddy --help

Run tests:

npm test

License

MIT — See LICENSE

Made with ❤️ for Claude Code developers