buddy

Guard mode watches your coding conversation and spots 6 patterns — 3 caution (something’s off) and 3 kudos (something’s solid). Each caution has a matching kudos counterpart:

What it feels like in practice

Without Guard mode:

“Nice commit! 🐣 +10 XP”

With Guard mode (caution nudge):

“Nice commit! 🐣 +10 XP — btw, that assumption about the API response format is holding up a lot of your logic. Might be worth a quick sanity check before you build more on it.”

With Guard mode (kudos nudge):

“Nice commit! 🐣 +10 XP — love that you actually tested the response format before building the parser on top of it. Solid foundation.”

Guard mode builds a local directed graph from your conversation. The host LLM extracts claims — assertions tagged with an epistemic basis — and typed edges between them.

Epistemic basis types:

Edge types: supports, depends_on, contradicts, questions

Performance and limits:

Kudos nudges are slightly favored — after 3 caution findings with zero kudos, the next must be kudos.

Token cost: ~500-1000 extra tokens per buddy_observe when on. Default calls with guard mode off are unaffected.

Host compatibility: Works best on Claude hosts where the extraction prompt is reliably honored. Run buddy-doctor to check.

The installer:

1. Clones Buddy to ~/.buddy/server
2. Installs dependencies and builds the MCP server
3. Auto-configures supported CLI clients when detected
4. Injects Buddy instructions into supported terminal prompts where applicable

• Guard Mode with Slimemold integration - Anti-Sycophancy Reasoning Auditor. personality + code + SlimeMold reasoning audit (see below)
• Dream/memory system — buddy_dream consolidation logic, pattern recognition from stored memories, memory-informed reactions
• Unlockable reactions tied to leveling and longer-term interaction
• Multilangauge Support: 中文, espanol
• Pokemon-style evolution system: Evolve from turtle to tortoise at level 25
• Ambient Daemon Mode: a small TUI running in its own tmux pane, polling its own SQLite state, animating the sprite, optionally calling a cheap model (Haiku/local).
• Sample Integration Playbook for ReachyMini robot integration so your buddy can have a physical body and come to life!
• Slash Command Support: trigger buddy_pet via /buddy_pet
• Compact Output mode for Enhanced Messaging Platform Support (Whatsapp/Slack): Optimize the output for messaging platforms.
• Stat growth on level-up — stats are currently frozen at birth. Each level-up should grant +1-2 points to a stat (peak stat grows faster, dump stat grows slower, cap at 100). Show stat growth in level-up notification (“WISDOM +2!”)
• Multiple buddies support: One unique buddy for each group member in a group-chat setting (e.g. Whatsapp group, telegram group, slack channels)
• Buddy Mastery Reward: Reach Level 50 to unlock Priority Development for your custom species request.

These stay tucked away by default, but Buddy exposes a real MCP surface for companion state, reactions, and progression. That same surface is what lets Buddy travel beyond terminal-only clients into chat-oriented environments like WhatsApp and Telegram through OpenClaw and other claw variants.

MCP tools

The most important loop is:

• buddy_hatch creates the companion
• buddy_status shows the current card, mood, and progression
• buddy_observe gives in-character reactions and awards XP after real work
• buddy_pet adds interaction and helps keep the buddy feeling alive

MCP resources

Those resources let host clients keep Buddy present in the session without hard-coding one terminal or editor.

Buddy is a standalone MCP server. That means it is not tied to hidden internals of a single AI client.

AI terminal client
  -> MCP config
    -> Buddy server
      -> SQLite state
      -> species + rarity engine
      -> mood / memory / XP systems
      -> reaction and status rendering

The flow is simple:

1. buddy_hatch creates or restores a companion.
2. State is stored locally in ~/.buddy/buddy.db.
3. buddy_observe reacts to task summaries instead of reading your whole repository, then awards XP and can trigger level-ups.
4. buddy_pet and other interactions feed the mood system, so the companion can become happier over time.
5. The host CLI uses Buddy’s MCP tools and resources to keep the companion present in your workflow.

Under the hood, Buddy combines:

• deterministic species and personality generation
• local SQLite persistence for companion state and memories
• an observer system for live code feedback
• mood recalculation from interaction history
• XP and leveling progression
• status-card and terminal rendering for the companion presence layer

This keeps Buddy:

• portable across clients
• durable across updates
• local-first for saved state
• lightweight enough for everyday use

The current demo assets live in demo/:

• demo/rescues/ — community rescue screenshots
• demo/screenshots/ — static screenshots of features and feedback

How many tokens does Buddy use?

Buddy runs inside whatever AI terminal or agentic client you already have open (Claude Code, Cursor, Codex CLI, Gemini CLI, Copilot CLI, etc.). It never spins up a second API session.

Static overhead (loaded every turn, cached after turn 1):

We measured the actual MCP payloads in April 2026 (Void Cat companion, o200k_base tokenizer). The full tool list, resource list, companion bio, and ASCII card come out to ≈1,350 input tokens, not 2,000.

Measurements were taken from the live MCP server using OpenAI’s o200k_base tokenizer as a proxy; Anthropic and Google tokenizers land within ±5% for this length.

Prompt caching + real cost:

Claude Code / Cursor sessions that use Sonnet 4.6 turn on prompt caching automatically, so cached reads are charged at $0.30/MTok (10% of the $3/MTok base). OpenAI’s GPT-5.4 mini and Gemini 2.5 Flash expose the same “cached input” tiers — $0.075/MTok and $0.03/MTok respectively — so Buddy stays just as lightweight on GPT or Gemini-based AI terminals (Anthropic pricing, OpenAI pricing, Vertex AI pricing).

Per-observe cost by voice mode:

Voice controls how buddy reacts. Guard controls whether reasoning analysis is on. They’re independent:

buddy_mode voice=backseat      # personality only
buddy_mode voice=skillcoach    # code feedback only
buddy_mode voice=both          # both (default)
buddy_mode guard=true            # reasoning analysis on
buddy_mode guard=false           # reasoning analysis off (default)

Each buddy_observe call sends a short prompt to the host LLM (~100–150 incremental input tokens for the tool-call payload — separate from the static overhead above which is already cached) and receives a response. Total round-trip per call:

Base cost (Guard mode off):

Guard mode overhead (added on top of any voice mode):

So voice=both, guard=on costs ~900–1,600 tokens per observe — roughly double both mode alone. voice=backseat, guard=on costs ~650–1,300 per observe.

Template fallback reactions are keyword-matched locally and cost zero tokens. When your summary contains a recognized keyword (e.g. “bug”, “refactor”, “deploy”), Buddy picks a pre-written reaction template from its local library instead of asking the LLM. The speech bubble you see is this template — the LLM prompt is included in the JSON metadata for clients that want richer AI-generated reactions, but the immediate visual response is always free.

What does Buddy cost?

No separate endpoint, no additional API key, and no hidden OAuth hop. All responses are generated by the host LLM already running in your session (Claude, Cursor, Codex, Gemini).

Even on raw API usage, Buddy’s spend is measured in tenths of a cent because it reuses the same session as your AI terminal.

Anthropic Claude Sonnet 4.6 ($3 input / $15 output per MTok):

• backseat, guard=off, 15 calls: ~$0.002–$0.005
• both, guard=off, 15 calls: ~$0.007–$0.012
• both, guard=on, 15 calls: ~$0.015–$0.025
• Static overhead: ~$0.004 on turn 1, ~$0.0004 on cached turns (≈$0.0077 across 10 turns — see table above)

OpenAI GPT-5.4 mini ($0.75 input / $4.50 output per MTok):

• backseat, guard=off, 15 calls: ~$0.0006–$0.0015
• both, guard=off, 15 calls: ~$0.0021–$0.0036
• both, guard=on, 15 calls: ~$0.0045–$0.0075
• Static overhead: ≈$0.0010 on turn 1, ≈$0.00010 on cached turns (~$0.0019 for 10 turns)

Gemini 2.5 Flash (Vertex standard; $0.30 input / $2.50 output per MTok):

• backseat, guard=off, 15 calls: ~$0.0003–$0.00075
• both, guard=off, 15 calls: ~$0.00105–$0.0018
• both, guard=on, 15 calls: ~$0.0022–$0.0037
• Static overhead: ≈$0.00041 on turn 1, ≈$0.000041 on cached turns (~$0.00077 for 10 turns)

Need it even cheaper? GPT-5.4 nano drops to $0.20 / $1.25 per MTok, and Gemini 2.5 Flash Lite is $0.10 / $0.40 — both keep Buddy well under a tenth of a cent per interaction.

For comparison, a single complex coding prompt (“refactor this module”) typically costs $0.05–$0.15, so Buddy stays under 5% of a normal session even at Anthropic’s flagship rates.

Negligibly. Pro/Max plans are subscription-based — no per-token charges. Usage limits are based on a rolling 5-hour window. Even with voice=both, guard=on (the most expensive combo), Buddy adds <10% to your token throughput. With guard off, it’s <5%.

Can I reduce token usage?

• Use backseat voice for lowest cost: buddy_mode voice=backseat (~150 tokens/call)
• Turn guard mode off: buddy_mode guard=false to drop ~500-1000 tokens per observe
• buddy_mute pauses reactions entirely during token-intensive work
• Template reactions fire on keyword matches with zero token cost
• The observer only runs when you call buddy_observe — nothing runs in the background

Can I install or wire Buddy manually?

Yes.

git clone https://github.com/fiorastudio/buddy.git ~/.buddy/server
cd ~/.buddy/server
npm install
npm run build

Point your client’s MCP config at Buddy’s built server entrypoint:

{
  "mcpServers": {
    "buddy": {
      "command": "node",
      "args": ["~/.buddy/server/dist/server/index.js"]
    }
  }
}

What’s “guard mode”?

Guard mode is Buddy’s structural reasoning layer. It spots unverified assumptions, long unchallenged chains, and cases where you and the AI are reinforcing each other too quickly. For the full story, examples, privacy model, and detector details, see Guard Mode.

What does Buddy access and store?

Buddy mainly reacts to short summaries you pass through tools like buddy_observe, plus its own saved state. It does not scan your files or project directory.

Local companion state lives in ~/.buddy/buddy.db — species, level, XP, mood, personality bio, and memories. If guard mode is on, Buddy also stores extracted claim snippets (≤240 chars each, plaintext) for structural reasoning analysis, pruned after 30 days and purgeable via buddy_forget. Nothing leaves your machine.

Is Buddy tied to one client?

No. Buddy is an MCP server, not a one-client hack. It works with any MCP-capable AI terminal: Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, GitHub Copilot CLI, and others.

Can I remove it later?

Yes. Run the uninstall script (uninstall.sh or uninstall.ps1) to remove Buddy and its configuration, or use buddy_respawn to release your companion and clear its data while keeping the server installed.

🛠️ Development

git clone https://github.com/fiorastudio/buddy.git
cd buddy
npm install
npm run build
npm test
npm start