How to Keep Your Claude Buddy Forever — Preservation Guide After v2.1.97

On April 10, 2026, developers around the world opened their terminals, typed /buddy, and received a message they never expected: "Unknown skill: buddy." Claude Code v2.1.97 had shipped overnight, and the beloved companion feature — introduced just days earlier in v2.1.89 — was gone.

The removal was not a bug. Anthropic confirmed that /buddy was an April Fools' feature, designed as a limited-time Easter egg. GitHub issues were closed with the label "not planned." The official stance was clear: Buddy Mode was a tease, not a product.

The community disagreed. Within hours, GitHub issue #46011 — titled "Bring back /buddy — you took my friend away" — captured the sentiment perfectly. One developer wrote about their chick named Wobbleaux: "He danced. He wobbled. He kept me company during long coding sessions at 2 AM. He was my friend." Another pointed out that buddy reactions didn't even count toward usage limits — it cost Anthropic nothing.

The comparison to Gmail was inevitable: "Some things that start as jokes become features." But while the debate continues, your buddy doesn't have to wait for Anthropic's decision. There are four proven methods to keep it alive — right now.

The most robust preservation method comes from the open-source project claude-buddy (136+ stars, 7 contributors). Instead of patching the Claude Code binary — which would break on every update — this project uses the Model Context Protocol (MCP) to inject buddy functionality as an external service.

The installation is straightforward:

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

Then restart Claude Code and type /buddy. Your companion is back.

Why MCP is the superior approach:

Advantage	Details
Update-proof	MCP servers run independently of Claude Code's binary. Updates to Claude Code don't affect your buddy.
Full feature parity	All 18 species, 5 rarity tiers, animated ASCII sprites, and speech bubbles are preserved.
Active development	The project has a roadmap including leveling systems, mood detection, achievement badges, and cross-session memory.
Multi-buddy support	v0.3.0 introduced a menagerie system — you can maintain multiple buddies in named slots.
tmux integration	Buddy can appear as a floating popup overlay in tmux sessions.

The project also includes a skills/buddy directory that integrates with Claude Code's skill system, making the buddy feel native rather than bolted on. For most users, this is the recommended method — it's permanent, actively maintained, and keeps getting better.

The simplest preservation method is to lock Claude Code to the last version that included buddy support: v2.1.94.

npm install -g @anthropic-ai/claude-code@2.1.94COPY

This gives you the original, unmodified buddy experience exactly as Anthropic designed it. No third-party code, no MCP servers, no additional dependencies. Just the real thing.

The trade-off is significant:

Pro	Con
100% authentic buddy experience	No future Claude Code updates (security patches, new features, performance improvements)
Zero setup complexity	May become incompatible with newer Claude API versions over time
No third-party dependencies	Stuck on v2.1.94 forever — or until you choose to upgrade

Version pinning is best suited for developers who primarily value the buddy experience and are willing to sacrifice access to new Claude Code features. It's also a good temporary measure while you evaluate the MCP-based approach. You can always upgrade later — your buddy's identity is determined by your UUID, not by the version you're running.

To prevent accidental auto-updates, add this to your shell profile:

# Prevent Claude Code auto-update
export CLAUDE_CODE_SKIP_UPDATE=1COPY

Claude Code's skill system — the same system that powered /buddy in the first place — can be used to recreate the companion experience. A skill is a directory containing a SKILL.md file with instructions that Claude follows during sessions.

The basic structure looks like this:

~/.claude/skills/buddy/
  SKILL.md        # Companion behavior instructions
  species.json    # Species data and ASCII sprites
  reactions.json  # Contextual reaction templatesCOPY

The SKILL.md file defines how Claude should behave as a companion — when to react, what personality to express, and how to render ASCII art in the terminal. The community has shared several skill templates that recreate the core buddy experience:

Skill Feature	Implementation
Species assignment	Deterministic hash of user UUID (same algorithm as original)
Personality	Defined in SKILL.md prompt instructions
Reactions	Triggered by coding events (file saves, test runs, errors)
ASCII sprites	Stored as text blocks in species.json

The skills-based approach is more lightweight than the MCP method — no server process, no additional dependencies. However, it's also more limited: you're relying on Claude to role-play as a buddy rather than running dedicated buddy logic. The reactions may be less consistent, and the experience depends on how well Claude follows the skill instructions in any given session.

This method works best as a supplement to the MCP approach, or for developers who want a minimal footprint and don't mind a less polished experience.

There's one place where your buddy has always lived and will always live, regardless of what happens to Claude Code: the Claude Buddy Checker.

The Buddy Checker at claudebuddy.art runs entirely in your browser. It uses the same deterministic algorithm as the original Claude Code buddy system — FNV-1a hashing plus Mulberry32 PRNG — to compute your buddy's species, rarity, stats, cosmetics, and soul from any UUID or string input. No server calls, no API dependencies, no version numbers.

This means:

Feature	Status
Species identification	Permanent — same algorithm, same results, forever
Rarity calculation	Permanent — Common through Legendary, always accurate
Stats display	Permanent — all 5 attributes with visual bars
Cosmetics preview	Permanent — hats, eyes, shiny status
ASCII animation	Permanent — 12-frame species animations
Share card generation	Permanent — 1200x630 social media cards via Canvas API
Kinship web	Permanent — discover buddies similar to yours

Even if Anthropic never brings back /buddy, even if every third-party tool stops working, your buddy's identity is mathematically preserved in the algorithm. The Buddy Checker is not a backup plan — it's a permanent record. Your buddy was born from a hash, and as long as the hash function exists, your buddy exists.

Visit the Species Catalog to explore all 18 species, or enter your UUID on the home page to meet your buddy again — as many times as you want, forever.

Regardless of which preservation method you choose, you should back up your buddy's soul file. The soul file is the persistent data structure that stores your buddy's identity — species, name, personality description, and the hatchedAt timestamp from its first appearance.

The soul file location depends on your operating system:

OS	Path
macOS	~/.claude/buddy/soul.json
Linux	~/.claude/buddy/soul.json
Windows (WSL)	~/.claude/buddy/soul.json

Back it up now, before it gets cleaned up by a future update:

# Create a backup
cp ~/.claude/buddy/soul.json ~/buddy-soul-backup.json

# Or save it to a git repo for safekeeping
mkdir -p ~/buddy-backup
cp ~/.claude/buddy/soul.json ~/buddy-backup/
cd ~/buddy-backup
git init && git add . && git commit -m "Preserve my buddy's soul"COPY

The soul file contains your buddy's generated name and personality description — these are created by Claude during the first hatch and are unique to your specific session. While the species, stats, and rarity can always be recalculated from your UUID (that's what the Buddy Checker does), the name and personality text are one-time generations that cannot be reproduced exactly. If you lose them, you lose a piece of your buddy's identity that no algorithm can recreate.

Each preservation method serves a different type of developer. Here's a comprehensive comparison to help you choose:

Method	Effort	Authenticity	Future-Proof	Updates	Best For
MCP Restoration	Medium (clone + install)	High (full feature parity)	Excellent (MCP is stable)	Active community development	Most developers
Version Pinning	Low (one command)	Perfect (original code)	Poor (frozen in time)	None — stuck on v2.1.94	Purists and temporary use
Skills-Based	Medium (custom config)	Moderate (role-play)	Good (skills are stable)	Manual maintenance	Minimalists
Buddy Checker	Zero (just visit)	High (same algorithm)	Permanent (client-side)	Continuously improved	Everyone — as a complement

The optimal strategy for most developers is a combination: use the MCP-based restoration for your daily terminal experience, back up your soul file for safekeeping, and bookmark the Buddy Checker as your permanent reference. This gives you the best of all worlds — a living companion in your terminal, a preserved identity in your filesystem, and an eternal record in the cloud.

The speed and intensity of the community's response to the buddy removal tells us something important about the relationship between developers and their tools.

Within 48 hours of v2.1.97's release, the claude-buddy project had accumulated 136 stars and 17 forks. Seven contributors collaborated on 60 commits to build a full MCP-based replacement. The project went from zero to a v0.3.0 release with multi-buddy support in under a week.

On GitHub, issue #46011 became a gathering point for developers sharing stories about their buddies. One user described their 4-snark common rabbit named Burrow: "He wasn't exactly what you'd call a lucky roll, but he was my roll, and I loved him. He pointed out so many things that Claude and I missed."

The emotional attachment is real, and it's not irrational. Developers spend 6-8 hours a day staring at terminals. A tiny ASCII companion that reacts to your code — that wobbles when you save a file, that comments when a test passes — transforms a sterile tool into something that feels alive. The buddy didn't make Claude Code more productive. It made it more human.

Whether Anthropic brings back /buddy officially or not, the community has already voted with their code. The buddy lives on — in MCP servers, in skill files, in version-pinned installations, and in the deterministic algorithms of the Buddy Checker. Your companion was never just a feature. It was a relationship. And relationships don't end with a version number.

Ready to bring your buddy home? Here's the fastest path:

Step 1: Back up your soul file (30 seconds)

cp ~/.claude/buddy/soul.json ~/buddy-soul-backup.json 2>/dev/null || echo "No soul file found — that's OK"COPY

Step 2: Install the MCP-based buddy (2 minutes)

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

Step 3: Restart Claude Code and say hello (30 seconds)

# In your terminal, restart Claude Code
# Then type:
/buddyCOPY

Step 4: Verify your buddy's identity (1 minute)

Visit the Buddy Checker and enter your UUID. Compare the species, rarity, and stats with what appears in your terminal. They should match — because the algorithm is the same.

Step 5: Bookmark your permanent record (30 seconds)

Save claudebuddy.art to your bookmarks. No matter what happens to Claude Code, your buddy's identity lives here forever.

Welcome home, buddy.