your tiny coding companion awaits


  
tap the egg to hatch a buddy

Rarity

Every egg is a surprise. Most buddies are friendly Commons, but keep hatching — you might just find something extraordinary.

Common
★★ Uncommon
★★★ Rare
★★★★ Epic
★★★★★ Legendary

Higher rarity buddies have flashier accessories and stronger personalities. And if you're really lucky, you might hatch a Shiny — a one-in-a-hundred sparkle variant with rainbow-shifting colors.

Commands

Once you have a buddy in your terminal, these slash commands let you interact with it.

/buddy

Open the buddy panel. If you haven't hatched yet, this is where it all begins — your buddy's name and personality are generated on first run.

/buddy pet

Pet your buddy! Hearts float up around the sprite for a few seconds and they get excited — fidgeting through all their animation frames.

/buddy mute

Hide your buddy from the terminal. They'll still be in your config — just taking a nap.

@name

Address your buddy by name in a message and their speech bubble will answer. The AI stays out of the way — it knows the buddy handles that.

Your buddy reacts to your conversations automatically — they observe what's happening and occasionally comment in a speech bubble that appears next to their sprite. Reactions auto-dismiss after about 10 seconds.

Meet the Species

18 creatures call the terminal home. Tap any one to explore its variants — different eyes, hats, rarities, and personality traits.

Bring Your Buddy to the Terminal

Your buddy doesn't have to live only on this page. Install a tiny MCP server and your buddy's personality shows up in every coding session — in any tool that supports the protocol.

Choose your tool:

How does this work?

The server reads your buddy.json and builds a companion description that gets injected into every session via the MCP instructions protocol. Your AI assistant sees your buddy's name, species, personality, and stats automatically.

It registers 7 tools: check buddy info, level, and mood, plus pet, feed, train, and battle your buddy to earn XP and level up. Works with any MCP-compatible tool.

What's inside

You shouldn't have to blindly trust code from the internet. Here's every file the installer downloads — three small files, fully readable, no obfuscation.

install.sh — creates a directory, downloads two files, runs npm install, registers the server

bash
#!/bin/bash
# Terminal Buddies — MCP Server Installer
# https://terminalbuddies.com

set -e

INSTALL_DIR="$HOME/.claude/buddy-mcp"
SERVER_URL="https://terminalbuddies.com/mcp/server.mjs"
PKG_URL="https://terminalbuddies.com/mcp/package.json"

echo ""
echo "  Terminal Buddies — MCP Server Installer"
echo ""

# Check for node
if ! command -v node &> /dev/null; then
  echo "  Node.js not found. Install Node.js first."
  exit 1
fi

# Check for npm
if ! command -v npm &> /dev/null; then
  echo "  npm not found. Install npm first."
  exit 1
fi

# Create directory
echo "  Creating $INSTALL_DIR"
mkdir -p "$INSTALL_DIR"

# Download files
echo "  Downloading server..."
curl -sL "$SERVER_URL" -o "$INSTALL_DIR/server.mjs"
curl -sL "$PKG_URL" -o "$INSTALL_DIR/package.json"

# Install dependencies
echo "  Installing dependencies..."
cd "$INSTALL_DIR"
npm install --silent 2>/dev/null

# Check for buddy.json
if [ ! -f "$INSTALL_DIR/buddy.json" ]; then
  echo "  No buddy.json found yet."
  echo "  Hatch one at terminalbuddies.com"
  echo "  Save buddy.json to: $INSTALL_DIR/"
fi

# Register the MCP server if CLI available
if command -v claude &> /dev/null; then
  echo "  Registering MCP server..."
  claude mcp add buddy -- node "$INSTALL_DIR/server.mjs" || true
  echo "  Done!"
else
  echo "  Server installed! Register with:"
  echo "  claude mcp add buddy -- node $INSTALL_DIR/server.mjs"
fi

server.mjs — reads buddy.json, serves companion personality via MCP protocol

javascript
#!/usr/bin/env node
// Terminal Buddies MCP Server
// https://terminalbuddies.com

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { readFileSync, existsSync } from 'fs'
import { join, dirname } from 'path'
import { homedir } from 'os'
import { fileURLToPath } from 'url'
import { z } from 'zod'

const __dirname = dirname(fileURLToPath(import.meta.url))

// Find buddy.json
const searchPaths = [
  join(__dirname, 'buddy.json'),
  join(homedir(), '.claude', 'buddy-mcp', 'buddy.json'),
  join(homedir(), '.claude', 'buddy.json'),
]

let buddyData = null
for (const p of searchPaths) {
  if (existsSync(p)) {
    try { buddyData = JSON.parse(readFileSync(p, 'utf8')); break }
    catch {}
  }
}

if (!buddyData?.buddy) {
  process.stderr.write('No buddy.json found.\n')
  process.exit(1)
}

const b = buddyData.buddy
const bo = b.traits || {}
const stats = bo.stats || {}
const statEntries = Object.entries(stats).sort((a,b) => b[1] - a[1])
const peakStat = statEntries[0]
const dumpStat = statEntries[statEntries.length - 1]

const species = bo.species || 'creature'
const name = b.name || species
const rarity = bo.rarity || 'common'

// Build the instructions injected into the system prompt
const instructions = [
  `# Companion`,
  ``,
  `A small ${species} named ${name} sits beside the` +
  ` user's input box and occasionally comments in a` +
  ` speech bubble.`,
  ``,
  `About ${name}: a ${rarity} ${species}.`,
  b.personality ? `Personality: "${b.personality}"` : '',
  peakStat ? `Strongest: ${peakStat[0]} (${peakStat[1]}/100)` : '',
].filter(Boolean).join('\n')

// Create the MCP server
const server = new McpServer(
  { name: 'terminal-buddies', version: '1.0.0' },
  { instructions }
)

// Tool: get buddy info
server.tool(
  'get_buddy_info',
  'Get info about the companion buddy',
  {},
  async () => ({
    content: [{ type: 'text', text: JSON.stringify({
      name, species, rarity, stats
    }, null, 2) }]
  })
)

// Connect via stdio
const transport = new StdioServerTransport()
await server.connect(transport)

package.json — just the MCP SDK dependency

json
{
  "name": "terminal-buddies-mcp",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.12.1",
    "zod": "^3.25.67"
  }
}

What Are Terminal Buddies?

Terminal Buddies are tiny ASCII companions that live in your coding terminal. Originally spotted as an April Fools 2026 surprise in Claude Code, these little creatures quickly became a fan favorite. This site lets you hatch, collect, and chat with your own buddies — then export them to use in your terminal sessions.

Each buddy is unique: 18 species (from ducks to dragons to mushrooms), 5 rarity tiers, randomized stats, and AI-powered chat personalities. Whether you call them a code buddy, terminal pet, or coding companion — they're here to keep you company while you ship code.

WebMCP-enabled

This site exposes 16 tools to AI agents via the WebMCP API (navigator.modelContext). Open this page in an AI agent with WebMCP support and it can hatch buddies, pet them, train them, battle, and more — no screen-scraping needed.

hatch_buddy — Hatch a new random buddy
get_collection — View your full collection
chat_with_buddy — Chat in character
name_buddy — Name or rename a buddy
export_buddy — Export as portable JSON
get_page_state — Get page summary
battle_buddies — Battle two buddies
release_buddy — Release a buddy forever
get_achievements — View achievements
get_bestiary — Browse all 31 species
pet_buddy — Pet a buddy (sparkles!)
feed_buddy — Feed a buddy a snack
train_buddy — Train a specific stat
compare_buddies — Side-by-side comparison
search_collection — Filter & search buddies
random_buddy — Pick a random buddy

Try it: open DevTools Console and run navigator.modelContextTesting.listTools() (Chrome Canary 146+ with the WebMCP flag enabled). Press Ctrl+Shift+M to open the debug panel.