Claude Code Buddy

Your Claude Code buddy — permanently. Survives every update.

Anthropic removed /buddy in Claude Code v2.1.97. This brings it back — forever. Same species, same stats, same personality. Now powered by MCP, so no update can ever take it away again.

📋 Requirements

• bun on PATH — claude-buddy's MCP server runs on bun. Install once: curl -fsSL https://bun.sh/install | bash
• Claude Code v2.1.80+
• Linux or macOS (Windows is experimental)

🚀 Quick Start

git clone https://github.com/1270011/claude-buddy
cd claude-buddy
bun install
bun run install-buddy

Then restart Claude Code and type /buddy. That's it.

💡 Want a global claude-buddy command? → bun link 💡 Need help? → bun run help or claude-buddy help (if linked) in terminal · /buddy help in Claude Code

Multiple Claude profiles?

If you run Claude Code with CLAUDE_CONFIG_DIR set (e.g. separate work and personal accounts), pass the same env var to install so buddy lands in the active profile and gets its own menagerie:

CLAUDE_CONFIG_DIR=~/.claude-personal bun run install-buddy
CLAUDE_CONFIG_DIR=~/.claude-personal bun run uninstall

The installer prints Target profile: <path> at the top so you can see at a glance which profile you're targeting. Each profile gets its own MCP entry, skill, hooks, status line, and $CLAUDE_CONFIG_DIR/buddy-state/ menagerie — installs in one profile don't touch another. With CLAUDE_CONFIG_DIR unset, behaviour is identical to single-profile (~/.claude/, ~/.claude-buddy/).

---

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   )  |_|    |_|   [ ==== ]   =(  ..  )=    |°  °|   (   ..   )
 `------'     |    |      `------'   (")__(")      |____|    `------'

Rarities

Rarity	Chance	Stars	Color
Common	60%	★	Gray
Uncommon	25%	★★	Green
Rare	10%	★★★	Blue
Epic	4%	★★★★	Purple
Legendary	1%	★★★★★	Gold

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

Stats

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

Why MCP Instead of Binary Patching?

Approach	Survives Updates	Animated	Comments	Risk
Binary patching	❌	❌	❌	Breaks on update
Pin old version	❌	✅	✅	No security fixes
claude-buddy	✅	✅	✅	None

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.

Repository Layout

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

---

In Claude Code

Command	Description
/buddy	Show companion card with ASCII art and stats
/buddy pet	Pet your companion
/buddy stats	Stats-only card
/buddy off / on	Mute / unmute reactions
/buddy rename <name>	Rename (1–14 chars)
/buddy personality <text>	Set custom personality
/buddy summon [slot]	Summon a saved buddy (omit slot for random)
/buddy save [slot]	Save current buddy to a named slot
/buddy list	List all saved buddies
/buddy dismiss <slot>	Remove a saved buddy slot
/buddy pick	Launch interactive TUI picker (! bun run pick)
/buddy frequency [seconds]	Show or set comment cooldown
/buddy style [classic|round]	Bubble border style (tmux only)
/buddy position [top|left]	Bubble position (tmux only)
/buddy rarity [on|off]	Show or hide stars + rarity line (tmux only)
/buddy width [10-60]	Set bubble text width in chars (tmux only)
/buddy margin [0-20]	Set right-side margin (tmux only)
/buddy statusline [on|off]	Enable or disable buddy in the status line
/buddy statusline combined	Show rate-limit usage bars alongside buddy (needs python3)
/buddy statusline basic	Switch back to buddy-only status line
/buddy help	Show all buddy commands

CLI

Command	Description
bun run install-buddy	Automated setup
bun run show	Show buddy in terminal
bun run pick	Interactive TUI to find and save your dream buddy
bun run hunt	Legacy search (use pick instead)
bun run doctor	Full diagnostic report
bun run verify	Verify buddy generation matches expected output
bun run backup	Snapshot / restore state
bun run settings	View / change buddy settings — cooldown, TTL (TUI coming soon)
bun run disable	Temporarily deactivate buddy
bun run enable	Re-enable buddy
bun run help	Full CLI reference
bun run cli/uninstall.ts	Clean removal

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

🎯 Buddy Pick

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.

bun run doctor

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

bun run test-statusline

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

bun run backup

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

---

Buddy not appearing in status line

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

Buddy comments not showing

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

Buddy art looks broken or misaligned

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

Recovery from a broken state

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

---

Requirement	Install
Bun	curl -fsSL https://bun.sh/install | bash
Claude Code v2.1.80+	Any version with MCP support
jq	apt install jq / brew install jq / windows: download and add 'jq.exe' from jqlang/jq to path

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.

---

🗺️ Roadmap

• Multi-buddy support — menagerie system with named slots, interactive TUI picker 💜@doctor-ew💜
• Leveling system — XP from coding sessions, unlockable reactions and upgrades
• Buddy pair-programming — active help during sessions, pattern detection
• Cross-session memory — remembers past projects and earlier conversations
• Mood system — shifts based on code quality, tests, time of day
• Achievement badges — "1000 lines reviewed", "week streak", etc. 💜ndcorder💜
• Light theme colors — auto-detect and match light theme RGB
• New species + community art — wyvern added 💜@jpmalone0💜 (community contributions welcome)
• npx claude-buddy — one-command install without cloning

---

💜 Contributors

Thank you to everyone who helped bring buddies back to life.

Automatically generated from the contributors graph via contrib.rocks.

Want to help? New species, better reactions, bugfixes, wild new features — PRs welcome.

---

🙏 Credits

• Original buddy concept by Anthropic (Claude Code v2.1.89 — v2.1.94)
• Inspired by any-buddy, buddy-reroll, ccbuddyy
• Built with the Model Context Protocol

---

📜 License

MIT — do whatever you want, just don't take my buddy away again.

Keywords: claude code buddy · claude code companion · claude code pet · terminal pet · coding companion · tamagotchi · MCP companion · /buddy command · claude buddy removed · bring back buddy · ASCII art pet