Buddy MCP
An MCP server with a pet for an agent terminal: it levels up, reacts to your work and in Guard mode flags shaky assumptions
- 119 ★ on the repository
- Last commit
Extended access
Why this level
- The installer edits client configuration, writes hooks and adds instructions to agent files
- Guard mode stores fragments of your conversation as plain text in a local database for 30 days
Install
- Works in
Manual install
curl -fsSL https://raw.githubusercontent.com/fiorastudio/buddy/master/install.sh | bashOn Windows: irm https://raw.githubusercontent.com/fiorastudio/buddy/master/install.ps1 | iex. The installer clones Buddy into ~/.buddy/server and configures clients.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The installer edits client configuration, writes hooks and adds instructions to agent files
- Guard mode stores fragments of your conversation as plain text in a local database for 30 days
This is third-party code. Review the repository files before installing.
What it does
Buddy is a local MCP server with a pet that lives in an agent's terminal and persists across sessions and clients. The project began as a replacement for the built-in `/buddy` command that was removed from Claude Code. The pet is one of 21 species with stats, a mood and levels, and the `buddy_observe` tool reacts in character to finished work and awards XP. The installer brings a previous pet back from `~/.claude.json` with the same name and species. The second feature, Guard mode, builds a local graph of claims from the conversation. It flags unjustified assumptions, long unchecked chains and moments when the human and the model agree too quickly, then gently surfaces one point worth checking. It is switched on with `buddy_mode guard=true` and adds 500 to 1,000 tokens per `buddy_observe` call. All replies are generated by your session's model, with no separate API key. State lives in `~/.buddy/buddy.db`, and the server has no network code.
Who it is for. Developers who spend long hours with an agent in the terminal and want a modest companion with memory and a gentle check on their own assumptions.
Good fit when
- You used `/buddy` in Claude Code and want the pet back with the same name, species and stats
- A session is stuck on an unvalidated premise and Guard mode can show which assumption holds the chain up
- One pet is wanted across several clients: Claude Code, Cursor, Codex CLI and Gemini CLI
- You want a pet card to share: `buddy_share` saves a PNG to `~/.buddy/shares/`
Not a fit when
- You need strict, formal reasoning checks: Guard gives hints in the pet's voice and is not a formal linter
- Token budgets are tight: Guard mode adds 500 to 1,000 tokens per `buddy_observe` call
- Installing via `curl | bash` is against policy: you would have to install manually from Git
Example request
Show my Buddy pet's status and turn on Guard mode for this conversation.MCP
- Transport
- stdio
- Authentication
- not required
Limitations
Node.js 18 or newer and Git are required. The installer clones Buddy into `~/.buddy/server`, builds the server and configures detected clients: it writes hooks and adds instructions to files such as `~/.codex/AGENTS.md` or `~/.cursor/rules/buddy.md`. Guard mode works best on Claude hosts where the claim-extraction prompt is reliably honored, which `buddy-doctor` can check. Claim snippets of up to 240 characters are stored in SQLite as plain text for 30 days. The author marks the `buddy_remember` and `buddy_dream` tools as not yet ready.
How to disable. Run uninstall.sh or uninstall.ps1 to remove Buddy and its configuration. The buddy_respawn tool releases the pet and clears its data while keeping the server installed.
FAQ
How do I install Buddy?
On macOS and Linux run `curl -fsSL https://raw.githubusercontent.com/fiorastudio/buddy/master/install.sh | bash`, on Windows `irm https://raw.githubusercontent.com/fiorastudio/buddy/master/install.ps1 | iex`. A wizard offers to rescue the old pet or hatch a new one, and `--no-onboard` skips it.
Can I install it manually?
Yes. Clone the repository into `~/.buddy/server`, run `npm install` and `npm run build`, and point the client's MCP config at `node ~/.buddy/server/dist/server/index.js`.
How many tokens does Buddy use?
The `backseat` voice uses about 150 tokens per call, and Guard mode adds 500 to 1,000 tokens per `buddy_observe`. Keyword template reactions cost no tokens, and `buddy_mute` pauses reactions.
Does Buddy read project files?
No. It reacts to short summaries you pass through `buddy_observe` and to its own saved state. It does not scan your files or project directory.
How do I delete the data?
The `buddy_forget` tool purges reasoning data for a session or entirely. The pet data and settings go with the uninstall script.
Discussion
No questions or reviews yet.
Related
MCP serversThe MCP endpoint of a Salt workspace on your server: an agent creates pages, databases and comments with a person rights.
A local assistant with an MCP bridge: Claude Code and Cursor search its memory, create tasks, send notifications and ask it questions
Cunzhi (寸止)
寸止 (Cunzhi)
MCP server in Rust and Tauri: the agent shows a dialog with options before ending a reply, keeps project rules and searches code
A local MCP server for Mac: Claude, Codex and ChatGPT work in apps, files, terminal and browser under your permissions
An MCP server and CLI that find in Claude Code and Codex sessions why a file became what it is: who asked the agent what, when and what changed
A desktop pet that reacts to Claude Code, OpenCode and Cursor through hooks and MCP without putting code, paths or secrets in its speech
README in short
The README frames the project as a rescue mission after the removal of `/buddy`: a pet, XP, 21 species and reactions to code. It then covers the quick install, Guard mode with its backstory and claim-graph design, per-client wiring details, species and stats, a roadmap, the MCP tool list, a cost breakdown and common questions.