coding-buddy

Coding Buddy

Your persistent coding companion — for Claude Code, Pi, and Oh My Pi. 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.

📦 Continuity / Migration

The claude-buddy package ended at v0.5.2.
@ramarivera/coding-buddy begins at v0.6.0 and is its continuation.

• Your existing buddy identity, menagerie, stats, and unlocks remain fully compatible.
• Legacy state and config identifiers (for example ~/.claude-buddy/, mcpServers["claude-buddy"]) are intentionally preserved so current installs keep working without reconfiguration.

📋 Requirements

• bun on PATH — the MCP server and extension runtime require Bun. Install once: curl -fsSL https://bun.sh/install | bash
• Linux or macOS (Windows is experimental)

Host	Minimum version	Identity source
Claude Code	v2.1.80+	accountUuid from ~/.claude.json
Pi	mariozechner/pi-coding-agent workspace	Stable random UUID persisted in ~/.pi/agent/buddy/identity.json
Oh My Pi (OMP)	OMP harness with omp.extensions support	Stable random UUID persisted in ~/.omp/agent/buddy/identity.json

All three surfaces use the same hero composition: the dashed speech bubble is on the left, its -- tail points toward the rarity-colored sprite on the right, and the companion name is centered underneath the sprite. The card recomputes against the current terminal width on every render.

🚀 Quick Start

Claude Code

npx -y @ramarivera/coding-buddy

This installs the MCP server, skill, hooks, and status line. Claude Code hooks are registered as thin bash wrappers with 15s timeouts; the wrappers locate Bun in bare hook environments and delegate behavior to TypeScript or the phase-2 legacy bash bridge. Restart Claude Code and type /buddy.

Pi

pi install npm:@ramarivera/coding-buddy

Pi registers the package's native extension and stores companion state under ~/.pi/agent/buddy.

Oh My Pi

omp plugin install @ramarivera/coding-buddy

OMP registers the package's native extension and stores companion state under ~/.omp/agent/buddy.

From source

git clone https://github.com/ramarivera/coding-buddy coding-buddy
cd coding-buddy
bun install
bun run install-buddy

💡 Want a global coding-buddy command? → bun link 💡 Need help? → bun run help, npx -y @ramarivera/coding-buddy help, or coding-buddy help (if linked) · /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 npx -y @ramarivera/coding-buddy install
CLAUDE_CONFIG_DIR=~/.claude-personal npx -y @ramarivera/coding-buddy 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/).

One companion across harnesses

To opt into one identity and one menagerie across Claude Code, Pi, and OMP, set the same variable before launching each harness:

export CODING_BUDDY_USER_ID="ramiro"

This opt-in uses ~/.coding-buddy/shared for the companion, XP, achievements, and reaction state. Set CODING_BUDDY_STATE_DIR when you need a different shared root. Sharing the state directory is intentional: it makes the companion actually follow you, at the cost of giving up separate per-harness progress. Without CODING_BUDDY_USER_ID, the existing Claude account identity and Pi/OMP per-harness identity.json behavior remain unchanged.

---

Every buddy is uniquely generated — same species, same stats, same personality every time. On Claude Code the seed is derived from your accountUuid in ~/.claude.json; on Pi and Oh My Pi a stable random UUID is generated once and persisted in ~/.pi/agent/buddy/identity.json or ~/.omp/agent/buddy/identity.json (unless CODING_BUDDY_USER_ID is set). 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, Pi, or Oh My Pi updates, your buddy stays.

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

• MCP Server — companion tools + system prompt that tells Claude to call buddy_react at the end of every turn. The tool call writes the reaction with source: "tool" — model-authored, renders nowhere in the transcript.
• 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 — backward-compat fallback chain. Skips if a fresh buddy_react (primary channel) just ran; otherwise extracts a legacy <!-- buddy: ... --> comment if Claude happens to emit one (older Claude Code builds), and otherwise picks a canned pool line via server/turn-reaction.ts. Every write carries a source tag (tool/comment/fallback) so /buddy stats can prove what produced the bubble.

Why MCP Instead of Binary Patching?

Approach	Survives Updates	Animated	Comments	Risk
Binary patching	❌	❌	❌	Breaks on update