# Coding Buddy ### Your persistent coding companion — for Claude Code, Pi, and Oh My Pi. Survives every update. [![Version](https://img.shields.io/github/v/release/ramarivera/coding-buddy?style=flat-square&color=6366f1)](https://github.com/ramarivera/coding-buddy/releases) [![License](https://img.shields.io/github/license/ramarivera/coding-buddy?style=flat-square&color=10b981)](LICENSE) [![Stars](https://img.shields.io/github/stars/ramarivera/coding-buddy?style=flat-square&color=f59e0b)](https://github.com/ramarivera/coding-buddy/stargazers) [![Claude Code](https://img.shields.io/badge/Claude%20Code-v2.1.80%2B-8b5cf6?style=flat-square)](https://claude.ai/code) [![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS-blue?style=flat-square)](#requirements) [![MCP](https://img.shields.io/badge/powered%20by-MCP-ec4899?style=flat-square)](https://modelcontextprotocol.io)
coding-buddy in action

coding-buddy in action

> **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.

🛡️

Survives Updates
_{MCP-based, not binary-patched. Your buddy lives through every Claude Code release.}

🎨

19 Species
_{From ducks to dragons — each with animated ASCII art and rarity colors.}

💬

Speech Bubbles
_{End-of-turn reactions come from the model by default (MCP tool call). When that doesn't fire — older Claude Code, no MCP, a turn where the model didn't react — a Stop hook falls back to a tagged canned pool line so the bubble is never silent.}

⚡

One-Command Install
_{Zero config. Works on any Claude Code v2.1.80+. Uninstall anytime.}

## 📦 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](https://bun.sh/install)** 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 ```bash 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 ```bash pi install npm:@ramarivera/coding-buddy ``` Pi registers the package's native extension and stores companion state under `~/.pi/agent/buddy`. ### Oh My Pi ```bash omp plugin install @ramarivera/coding-buddy ``` OMP registers the package's native extension and stores companion state under `~/.omp/agent/buddy`. ### From source ```bash 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: ```bash 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: ` 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: ```bash 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.
---

🐙 Meet the 19 Species

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.

all 18 species

``` 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.

---

🏗️ How It Works

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 `` 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 | | Pin old version | ❌ | ✅ | ✅ | No security fixes | | **coding-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 ``` coding-buddy/ ├── server/ # MCP server — tools, engine, art, reactions, state ├── skills/buddy/ # /buddy slash command ├── hooks/ # Thin Claude Code hook wrappers and phase-2 legacy bash hooks ├── server/hooks/ # Hook behavior implemented in TypeScript ├── statusline/ # Animated right-aligned buddy display └── cli/ # install, show, hunt, verify, doctor, backup, uninstall ```

---

🛠️ Commands Reference

### 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 ` | Rename (1–14 chars) | | `/buddy personality ` | 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 ` | Remove a saved buddy slot | | `/buddy pick` | Launch interactive TUI picker (`! npx -y @ramarivera/coding-buddy 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 You can run any command with `npx -y @ramarivera/coding-buddy ` from anywhere, or `bun run