🐾 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.