Collectible companion creatures for Claude Code — discover, catch, and level up Buddymon through your coding sessions
46734e79c8
When an active encounter exists and the next Bash tool call produces output with no matching error patterns, the monster is automatically defeated and XP is awarded — no manual /buddymon fight needed. /buddymon fight is kept as a manual fallback for fixes that happen outside Bash (config edits, etc.). |
||
|---|---|---|
| .claude-plugin | ||
| hooks | ||
| hooks-handlers | ||
| lib | ||
| skills/buddymon | ||
| .gitignore | ||
| 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.