buddymon/README.md

🐾 Buddymon

A Claude Code extension that turns your coding sessions into a creature-collecting game.

Buddymon are discovered, caught, and leveled up through real development work — not separate from it.

How it works: Buddymon uses Claude Code's hook and plugin system — it is not a UI mod. Notifications (encounters, XP, session summaries) appear as system-injected context in the chat thread, visible to both you and Claude. They do not appear in Thrumble's speech bubble or any other CC UI widget.

Thrumble and Buddymon

Thrumble is Anthropic's own companion widget built into Claude Code. Buddymon is a separate community plugin — there is no official relationship between them. The CC plugin API does not expose a hook to drive Thrumble's speech bubble, so Buddymon cannot make Thrumble announce encounters. If Anthropic ships a companion speech API in a future release, Buddymon will adopt it.

Until then, Buddymon notifications arrive as chat context rather than Thrumble barks. All game state (XP, encounters, roster) works regardless.

---

What it does

• Bug monsters spawn from error output during your session (TypeErrors, CORS errors, race conditions, etc.)
• Buddymon are companions you assign to sessions — they gain XP and propose challenges
• Challenges are proactive goals your buddy sets at session start (write 5 tests, implement a feature in 30 min, net-negative lines)
• Encounters require you to fight or catch — catch rate improves if you write a failing test, isolate the repro, or add a comment

---

Requirements

• Claude Code CLI
• Python 3 (already required by Claude Code)
• bash

---

Install

Clone the repo anywhere and run the install script:

git clone https://git.opensourcesolarpunk.com/Circuit-Forge/buddymon.git
cd buddymon
bash install.sh

Then restart Claude Code and run:

/buddymon start

The install script:

• Creates a local circuitforge marketplace under ~/.claude/plugins/marketplaces/circuitforge/ (required — CC validates plugin names against the marketplace index)
• Symlinks the repo into ~/.claude/plugins/cache/circuitforge/buddymon/<version>/
• Registers the plugin in ~/.claude/plugins/installed_plugins.json and ~/.claude/plugins/known_marketplaces.json
• Enables it in ~/.claude/settings.json
• Creates ~/.claude/buddymon/ state directory with initial JSON files

Because it uses a symlink, any git pull in the repo is immediately live — no reinstall needed.

Mirrors

You can clone from any of the three remotes:

# Forgejo (primary)
git clone https://git.opensourcesolarpunk.com/Circuit-Forge/buddymon.git

# GitHub
git clone https://github.com/CircuitForgeLLC/buddymon.git

# Codeberg
git clone https://codeberg.org/CircuitForge/buddymon.git

Uninstall

bash install.sh --uninstall

Removes the symlink, deregisters from installed_plugins.json, and removes the enabledPlugins entry. Your ~/.claude/buddymon/ state (roster, XP, encounters) is left intact.

---

Commands

One command, all subcommands:

Usage	Description
/buddymon	Status panel — active buddy, XP, challenge, encounter
/buddymon start	Choose your starter (first run only)
/buddymon assign <name>	Assign a buddy to this session
/buddymon fight	Fight the current bug monster
/buddymon catch	Attempt to catch the current bug monster
/buddymon roster	View full roster
/buddymon help	Show command list

---

Bug Monsters

Spawned from error output detected by the PostToolUse hook:

Monster	Trigger	Rarity
👻 NullWraith	NullPointerException, AttributeError: NoneType	Common
😈 FencepostDemon	IndexError, ArrayIndexOutOfBounds	Common
🔧 TypeGreml	TypeError, type mismatch	Common
🐍 SyntaxSerpent	SyntaxError, parse error	Very common
🌐 CORSCurse	CORS policy blocked	Common
♾️ LoopLich	Timeout, RecursionError, stack overflow	Uncommon
👁️ RacePhantom	Race condition, deadlock, data race	Rare
🗿 FossilGolem	DeprecationWarning, legacy API	Uncommon
🔒 ShadowBit	Security vulnerability patterns	Rare — catch only
🌫️ VoidSpecter	404, ENOENT, route not found	Common
🩸 MemoryLeech	OOM, memory leak	Uncommon

---

Buddymon (Starters)

Buddy	Affinity	Discover trigger
🔥 Pyrobyte	Speedrunner	Starter choice
🔍 Debuglin	Tester	Starter choice
✂️ Minimox	Cleaner	Starter choice
🌙 Noctara	Nocturnal	Late-night session (after 10pm, 2+ hours)
🗺️ Explorah	Explorer	First time writing in a new language

---

State

All state lives in ~/.claude/buddymon/ — never in the repo.

~/.claude/buddymon/
├── roster.json        # owned Buddymon, XP, levels
├── encounters.json    # encounter history + active encounter
├── active.json        # current session assignment + challenge
└── session.json       # session stats (reset each session)

---

A CircuitForge LLC project. MIT license.