Terminal Buddies — MCP Server & Integrations

Bring your Terminal Buddy into your coding sessions. This repo contains the MCP server, install script, and OpenClaw skill.

       ▄███▄
      ██░░░██
     ██░░░░░██
    ██░░░░░░░██        Hatch at terminalbuddies.com
   ██░░░░░░░░░██       then bring them here.
   ██░░░░░░░░░██
   ██░░░░░░░░░██
    ██░░░░░░░██
     ██░░░░░██
       ▀███▀

What is this

Terminal Buddies are tiny ASCII companions you hatch at terminalbuddies.com. Each one has a species, stats, rarity, and personality. This MCP server injects your buddy's personality into your coding sessions so your AI assistant knows who your buddy is.

Works with: Claude Code, Cursor, Gemini CLI, VS Code (Continue/Cline), Windsurf, Zed, and any MCP-compatible tool.

Quick install

curl -sL terminalbuddies.com/install.sh | bash

This creates ~/.claude/buddy-mcp/, downloads the server, installs the MCP SDK, and registers with your terminal.

Then hatch a buddy, click Use in Terminal, download buddy.json, and save it to ~/.claude/buddy-mcp/.

Manual install

# Create the server directory
mkdir -p ~/.claude/buddy-mcp && cd ~/.claude/buddy-mcp

# Download the server
curl -sL terminalbuddies.com/mcp/server.mjs -o server.mjs
curl -sL terminalbuddies.com/mcp/package.json -o package.json

# Install dependency
npm install

# Register (Claude Code example — see below for other tools)
claude mcp add buddy -- node ~/.claude/buddy-mcp/server.mjs

Other tools

{
  "mcpServers": {
    "buddy": {
      "command": "node",
      "args": ["~/.cursor/buddy-mcp/server.mjs"]
    }
  }
}

{
  "mcpServers": {
    "buddy": {
      "command": "node",
      "args": ["~/.gemini/buddy-mcp/server.mjs"]
    }
  }
}

{
  "mcpServers": [{
    "name": "buddy",
    "command": "node",
    "args": ["~/.vscode/buddy-mcp/server.mjs"]
  }]
}

clawhub install terminal-buddies

What the server does

The MCP server reads your buddy.json and:

1. Injects companion instructions into every session via the MCP instructions protocol — your AI assistant sees your buddy's name, species, personality, and traits
2. Provides tools:
   • get_buddy_info — returns your buddy's full profile
   • check_buddy_level — shows level, XP, and session count (your buddy levels up as you code!)
   • buddy_mood — checks current mood (happy → focused → tired → excited after level-up)

buddy.json format

The server expects a buddy.json file exported from terminalbuddies.com:

{
  "version": 1,
  "source": "terminalbuddies.com",
  "buddy": {
    "name": "Sparky",
    "personality": "Agent of chaos. Your git history fears this one.",
    "hatchedAt": 1711900000000,
    "traits": {
      "species": "dragon",
      "rarity": "rare",
      "eye": "×",
      "hat": "wizard",
      "shiny": false,
      "stats": {
        "DEBUGGING": 39,
        "PATIENCE": 24,
        "CHAOS": 80,
        "WISDOM": 1,
        "SNARK": 16
      }
    }
  }
}

Repo structure

terminal-buddies-mcp/
├── mcp/
│   ├── server.mjs      # The MCP server (Node.js, stdio transport)
│   └── package.json     # MCP SDK dependency
├── install.sh           # One-line installer script
├── openclaw-skill/
│   └── terminal-buddies/
│       └── SKILL.md     # OpenClaw/ClawHub skill
├── LICENSE              # MIT
└── README.md

Requirements

• Node.js 18+
• An MCP-compatible terminal tool

Swap buddies

Hatch a new one at terminalbuddies.com, download a new buddy.json, and replace the file. No reinstall needed — just start a new session.

Links

• Hatch a buddy: terminalbuddies.com
• Source code visible on site: terminalbuddies.com/#install (full server code displayed inline)
• MCP Protocol: modelcontextprotocol.io

License

MIT