Every buddy is uniquely generated from your Claude Code account — same species, same stats, same personality every time. 19 species, each with 3 idle animation frames + a blink.

 duck        goose       blob        cat         dragon      octopus
   __         (°>        .----.       /\_/\      /^\  /^\     .----.
 <(° )___      ||       ( °  ° )    ( °   °)   <  °  °  >   ( °  ° )
  (  ._>     _(__)_     (      )    (  ω  )    (   ~~   )   (______)
   `--'       ^^^^       `----'     (")_(")     `-vvvv-'    /\/\/\/\

 owl         penguin     turtle      snail       ghost       axolotl
  /\  /\      .---.       _,--._    °    .--.    .----.    }~(______)~{
 ((°)(°))    (°>°)       ( °  ° )    \  ( @ )   / °  ° \  }~(° .. °)~{
 (  ><  )   /(   )\      [______]     \_`--'    |      |    ( .--. )
  `----'     `---'       ``    ``    ~~~~~~~    ~`~``~`~     (_/  \_)

 capybara    cactus      robot       rabbit      mushroom    chonk
 n______n   n  ____  n    .[||].      (\__/)    .-o-OO-o-.  /\    /\
( °    ° )  | |°  °| |   [ °  ° ]    ( °  ° )  (__________)( °    ° )
(   oo   )  |_|    |_|   [ ==== ]   =(  ..  )=    |°  °|   (   ..   )
 `------'     |    |      `------'   (")__(")      |____|    `------'

Colors use 24-bit true color matching Claude Code's dark theme exactly.

Every buddy has 5 core stats: DEBUGGING · PATIENCE · CHAOS · WISDOM · SNARK

High SNARK buddies are sarcastic. High WISDOM ones are insightful. High CHAOS ones are unpredictable. Each buddy has a peak stat and a dump stat.

Five integration points, zero binary dependencies. When Claude Code updates, your buddy stays.

┌────────────── Claude Code (any version) ──────────────┐
│                                                        │
│   MCP Server    Skill       Status Line    Hooks       │
│  (buddy tools) (/buddy)    (animated art) (comments)   │
└───────────────────────┬────────────────────────────────┘
                        │ stable extension points
             ┌──────────┴──────────┐
             │    claude-buddy     │
             │                     │
             │  wyhash + mulberry32│
             │  18 species, 3 anim │
             │  rarity colors      │
             │  speech bubbles     │
             │  ~/.claude-buddy/   │
             └─────────────────────┘

• MCP Server — companion tools + system prompt that instructs Claude to write buddy comments
• Skill — routes /buddy, /buddy pet, /buddy stats, /buddy off, /buddy rename
• Status Line — animated ASCII art, right-aligned, with rarity color and speech bubble
• PostToolUse Hook — detects errors, test failures, large diffs in Bash output
• Stop Hook — extracts invisible <!-- buddy: ... --> comments from Claude's responses

MCP is an industry-standard protocol. Skills are Markdown files. Hooks and status line are shell scripts. Nothing depends on Claude Code's binary internals.

claude-buddy/
├── server/          # MCP server — tools, engine, art, reactions, state
├── skills/buddy/    # /buddy slash command
├── hooks/           # PostToolUse + Stop hooks (error & comment detection)
├── statusline/      # Animated right-aligned buddy display
└── cli/             # install, show, hunt, verify, doctor, backup, uninstall

_{💡 Want a global claude-buddy command? → cd claude-buddy && bun link}

Want a specific species, rarity, or stat distribution?

bun run pick

Interactive TUI with saved buddies, criteria search, vim keys, and two-pane preview. Uses the exact same wyhash + mulberry32 algorithm as Claude Code.

claude-buddy ships with built-in diagnostics for debugging across terminals and platforms.

Complete diagnostic — environment, terminal info, state, settings, padding test, live status line output. Always run this first when filing a bug report.

Temporarily replaces your status line with a multi-line diagnostic. Shows padding strategies side-by-side, color support, Unicode handling.

bun run test-statusline          # install test
# restart Claude Code, screenshot
bun run test-statusline restore  # restore buddy

Snapshot all claude-buddy state to a timestamped backup. Use before experiments.

bun run backup              # create snapshot
bun run backup list         # list snapshots
bun run backup restore      # restore latest
bun run backup restore <ts> # restore specific

1. Run bun run doctor — does the script work directly?
2. Restart Claude Code completely — instructions are loaded once at session start
3. Check ~/.claude/settings.json has the statusLine block
4. Make sure bun and jq are in $PATH

The buddy comment mechanism uses an MCP server instructions field that Claude only reads at session start. If you installed claude-buddy in an existing session, restart Claude Code.

jq '.mcpServers["claude-buddy"]' ~/.claude.json

Known MVP issue on some terminal/platform combos — different terminals render Braille Pattern Blank (U+2800) at different widths.

To help us fix it:

1. Run bun run doctor and paste output in a new issue
2. Run bun run test-statusline and screenshot the result
3. Then bun run test-statusline restore

bun run backup restore      # restore latest backup
bun run cli/uninstall.ts    # full clean removal

Will I get the same buddy I had? Yes. claude-buddy uses the exact same algorithm as the original (wyhash + mulberry32, same salt, same identity resolution). If your ~/.claude.json still has your accountUuid, you'll get the identical species, rarity, stats, and cosmetics.