148 lines
5.3 KiB
Markdown
148 lines
5.3 KiB
Markdown
# 🐾 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.
|
|
|
|
### Companion widgets and Buddymon
|
|
|
|
Claude Code supports personal companion widgets — small characters that sit beside the input box and comment in a speech bubble. These are user-configured, not built into CC by Anthropic. Buddymon is a separate community plugin and has no relationship to any specific companion.
|
|
|
|
The CC plugin API does not expose a hook to drive companion speech bubbles, so Buddymon cannot make your companion 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 companion 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](https://claude.ai/code) CLI
|
|
- Python 3 (already required by Claude Code)
|
|
- bash
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
Clone the repo anywhere and run the install script:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
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](https://circuitforge.tech) project. MIT license.*
|