claude_buddy

Choose your own Claude Code companion pet. Pick your species, rarity, eyes, hat, and stats — then apply it instantly.

npx claude_buddy

No Bun required. No native addons. Just Node 18+.

What it does

Claude Code assigns you a random companion pet based on your account ID. You can't change it through normal means. claude_buddy lets you pick exactly the pet you want by finding a salt that produces your desired combination, then patching the Claude Code binary to use it.

$ claude_buddy current

  Your default pet (original salt)

  GOOSE ★

    Eye: ×   Hat: none

  Stats:
    DEBUGGING  ███████░░░░░░░░░░░░░ 35
    PATIENCE   ░░░░░░░░░░░░░░░░░░░░ 1
    CHAOS      ███░░░░░░░░░░░░░░░░░ 14
    WISDOM     ████████████░░░░░░░░ 59
    SNARK      ███░░░░░░░░░░░░░░░░░ 15

$ claude_buddy -s dragon -r legendary -e ✦ -t wizard -y

  Searching (estimated ~8640 attempts)...
  Found in 4231 attempts (892ms)

  DRAGON ★★★★★

    Eye: ✦   Hat: wizard

  Stats:
    DEBUGGING  ████████████████████ 98
    ...

  Patched 3 occurrences
  Done! Launch Claude Code to see your new companion.

Install

npx claude_buddy          # run directly
npm install -g claude_buddy  # or install globally

Requires Node.js 18+. That's it.

Commands

| Command | What it does | |---------|-------------| | claude_buddy | Interactive pet picker (default) | | claude_buddy preview | Browse pets without applying | | claude_buddy current | Show your default + patched pet | | claude_buddy apply | Re-apply saved pet after Claude Code updates | | claude_buddy restore | Restore your original pet + remove hook | | claude_buddy rehatch | Delete companion for a fresh /buddy hatch |

Options

-s, --species <name>     duck, goose, blob, cat, dragon, octopus, owl,
                         penguin, turtle, snail, ghost, axolotl, capybara,
                         cactus, robot, rabbit, mushroom, chonk

-r, --rarity <level>     common (60%), uncommon (25%), rare (10%),
                         epic (4%), legendary (1%)

-e, --eye <char>         · ✦ × ◉ @ °

-t, --hat <name>         crown, tophat, propeller, halo, wizard,
                         beanie, tinyduck (common rarity always gets none)

-n, --name <name>        Rename your companion
-p, --personality <desc> Set companion personality description

--shiny                  Require shiny variant (~100x longer search)
--peak <stat>            Best stat (DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK)
--dump <stat>            Worst stat

-y, --yes                Skip all confirmation prompts
--no-hook                Don't offer to install the auto-patch hook
--silent                 Suppress output (for apply command in hooks)

Quick Templates

Copy-paste one of these to get a specific pet instantly:

# Legendary dragon with wizard hat and star eyes
claude_buddy -s dragon -r legendary -e ✦ -t wizard -y

# Epic cat with halo and circle eyes
claude_buddy -s cat -r epic -e ◉ -t halo -y

# Rare ghost with crown and dot eyes
claude_buddy -s ghost -r rare -e · -t crown -y

# Legendary axolotl with tinyduck hat
claude_buddy -s axolotl -r legendary -e ° -t tinyduck -y

# Epic robot with tophat and x eyes
claude_buddy -s robot -r epic -e × -t tophat -y

# Legendary octopus with propeller hat (shiny!)
claude_buddy -s octopus -r legendary -e ✦ -t propeller --shiny -y

# Rare capybara with beanie and at eyes
claude_buddy -s capybara -r rare -e @ -t beanie -y

# Common duck (no hat, fastest search)
claude_buddy -s duck -r common -e · -y

Search times: Common combos take <1 second. Legendary takes a few seconds. Adding --shiny takes 30-60 seconds.

Examples

# Interactive — walks you through everything
claude_buddy

# Preview without applying
claude_buddy preview -s cat -r epic

# See what you have now
claude_buddy current

# After a Claude Code update
claude_buddy apply

# Go back to your original pet
claude_buddy restore

Auto-patch hook

Claude Code updates can reset your pet. During setup, claude_buddy offers to install a SessionStart hook that re-applies your pet automatically (~50ms overhead). You can also install it manually:

claude_buddy apply --silent  # what the hook runs

To remove the hook:

claude_buddy restore

How it works

1. Generates your pet using the same algorithm as Claude Code — wyhash + Mulberry32 PRNG seeded from userId + salt
2. Brute-forces a salt that produces your desired species/rarity/eye/hat combination using worker_threads
3. Patches the Claude Code binary by replacing the salt string at all occurrences (same length, no offset shifts)
4. Re-signs the binary on macOS with codesign --force --sign -
5. Backs up the original binary before the first patch

The wyhash implementation is pure JavaScript (BigInt arithmetic), tested against Bun.hash() with 25 fixture pairs for bit-exact parity. No Bun dependency needed.

Safety

• Creates a backup of the Claude Code binary before patching (<binary>.claude_buddy-bak)
• Uses atomic file writes (temp file + rename) so the binary is never in a half-written state
• Verification step confirms the new salt is present at all expected offsets
• claude_buddy restore always works — patches back to the original salt
• The backup file is never deleted automatically

License

MIT