Collectible companion creatures for Claude Code — discover, catch, and level up Buddymon through your coding sessions
e9b04070f3
- install.sh: symlink-based dev install, registers in installed_plugins.json and settings.json, initializes ~/.claude/buddymon/ state files - install.sh --uninstall to cleanly remove - Fix stale /buddymon-start and /buddymon-assign references in session-start.sh to use unified /buddymon start and /buddymon assign subcommands |
||
|---|---|---|
| .claude-plugin | ||
| hooks | ||
| hooks-handlers | ||
| lib | ||
| skills/buddymon | ||
| .gitignore | ||
| install.sh | ||
| LICENSE | ||
| README.md | ||
🐾 Buddymon
A Claude Code plugin 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.
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
Install
# From the Claude Code marketplace (once listed):
/install buddymon
# Or manually — clone and add to your project's .claude/settings.json:
git clone https://git.opensourcesolarpunk.com/Circuit-Forge/buddymon.git ~/.claude/plugins/local/buddymon
Then add to ~/.claude/settings.json:
{
"enabledPlugins": {
"buddymon@local": true
}
}
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)
Mirrors
- Primary: https://git.opensourcesolarpunk.com/Circuit-Forge/buddymon
- GitHub: https://github.com/CircuitForgeLLC/buddymon
- Codeberg: https://codeberg.org/CircuitForge/buddymon
A CircuitForge LLC project. MIT license.