install.sh now copies hooks-handlers/*.py and hooks.json into the live
cache dir after symlinking — ensures edits take effect in the running
session without a CC restart for hook scripts, and on next session start
for hooks.json changes.
Also manually synced 0.1.0 cache to unblock current session:
- post-tool-use.py: find_catalog + already-owned spawn guard
- user-prompt-submit.py: null buddymon_id fallback
- roster-stop.py: reads roster_output.txt (no recursive CLI call)
- hooks.json: roster-stop.py Stop hook entry
- post-tool-use: find_catalog() checks ~/.claude/buddymon/catalog.json first
so Veritarch is always found regardless of which cache CLAUDE_PLUGIN_ROOT
points to; fixes 'your buddy' display bug
- post-tool-use: skip spawn when monster already in collection (was only
checked on existing encounters, not at spawn time; caused already-caught
monsters to re-announce)
- post-tool-use: fix spawn block indentation — set_active_encounter was
outside the else, running even on already-owned skip
- user-prompt-submit: same null buddymon_id fallback fix as post-tool-use
- cli.py cmd_roster: buffer all output to StringIO; write roster_output.txt
+ roster_pending.txt; suppress stdout when piped (isatty check)
- roster-stop.py: read roster_output.txt directly instead of re-running cli.py
(eliminated the recursive flag-write loop); remove unused subprocess import
Roster (cli.py):
- Fully restructured cmd_roster with four clearly-labelled sections:
BUDDYMON (✓ levels via XP), LANGUAGE MASCOTS (✓ levels via XP),
LANGUAGE AFFINITIES (◑ passive), BUG TROPHY CASE (✗ trophies only)
- Evolution chain shown inline per-buddy (Debuglin → [Verifex] → Veritarch)
- Active buddy marked ← ACTIVE; next-evo target with levels-to-go
- Language affinities show element + 🦎 tag when a mascot is available
- Bug trophy grid: two-column, element tags, notable levels shown
- Writes roster_pending.txt to trigger Stop hook delivery (no truncation)
Stop hook (roster-stop.py + hooks.json):
- New Stop hook reads roster_pending.txt; runs cli.py roster; emits full
output as additionalContext; clears the flag — fires once per invocation
- Avoids Bash tool result truncation for long roster output
Bug fixes (post-tool-use.py):
- get_session_state(): fall through to active.json when buddymon_id is null
or missing (pgrp mismatch between CLI process and hook process)
- get_active_buddy_id(): guard against caught_bug_monster type slipping in
as the active buddy (ThrottleDemon state corruption fix)
- Language "new territory" message now uses affinity XP == 0 as the sole
signal — drops volatile session.json languages_seen check that caused
spurious "New language spotted" fires across sessions
- Already-owned encounter shortcut: instant dismiss with no wound cycle
Language mascots:
- 11 mascots across common/uncommon/rare/legendary tiers (Pythia, Asynclet,
Bashling, Goroutling, Typeling, Vueling, Querion, Ferrix, Perlius,
Cobolithon, Lispling)
- Full evolution chains for all mascots (16 evolutions total in catalog)
- Spawn via PostToolUse after language affinity milestones; probability
scales with affinity level; only fires with no active encounter
- Passive strength reduction: each Write/Edit in the mascot's language
ticks current_strength down (floor 5%, triggers re-announcement)
- Mascot-aware catch formula: base_rate + affinity_bonus (6% per level) +
weakness_bonus + soft element gating via existing player_elements
- Language-themed weakening menu and catch failure messages in CLI
- Caught mascots stored as type="caught_language_mascot"; assignable as buddy
- UserPromptSubmit uses distinct 🦎 announcement with language context
Roster display:
- New "Language Mascots" section between core buddymon and caught bug monsters
- Language affinity table marks languages with spawnable mascots (🦎)
- Discovery counter now tracks both bug monsters and mascots separately
Veritarch (third evolution):
- Debuglin → Verifex (Lv.100) → Veritarch (Lv.200)
- TYPE FORTRESS / INVARIANT PROOF / ZERO FLAKE challenges
- xp_multiplier 1.7, catch_rate 0.90
Script-first architecture:
- All game logic extracted to lib/cli.py (~850 lines); SKILL.md is now
a ~55-line relay — 88% token reduction per invocation
- CLI emits [INPUT_NEEDED] and [HAIKU_NEEDED] markers for interactive flows
- PostToolUse hook re-emits CLI stdout as additionalContext for inline display
Session XP fix:
- statusline.sh and session state now read from sessions/<pgrp>.json
(per-window) with fallback to active.json; fixes stale XP in statusline
Auto-attack rates were flat 50%/35% regardless of encounter rarity or buddy
level, and parallel sessions could each roll independently against the same
encounter — compounding to ~87.5% effective wound rate with 3 sessions open.
Wound rates by rarity (base, before level scaling):
very_common: 55% common: 40% uncommon: 22% rare: 10% legendary: 2%
Auto-resolve rates by rarity:
very_common: 45% common: 28% uncommon: 14% rare: 5% legendary: 1%
Level multiplier: 1.0 + (level / 100) * 0.25 — Lv.44 adds ~11% to each.
So Lv.44 vs common: wound=44%, resolve=31%. Lv.44 vs rare: wound=11%, resolve=6%.
Wound cooldown: encounters stamped with last_wounded_at. Any session that
would wound/resolve within 30s of the last wound is skipped — prevents
parallel sessions from pile-driving the same encounter.
Previously the catch roll script wrote catch_pending=False to disk before
the Bash process exited. The PostToolUse hook fired after exit, saw False,
and could auto-resolve the encounter on the same run as the catch attempt.
Fix: the hook now owns the flag lifecycle.
- Hook clears catch_pending after consuming it (protects exactly one run)
- Roll script never touches catch_pending (no premature clear)
- On failure, flag stays True through the roll, cleared by hook afterward
- Next /buddymon catch call re-sets it at the top as before
Net effect: a failed catch attempt always gets one full clean Bash run of
grace before auto-resolve can fire again.
Skills run via Bash heredoc don't inherit CLAUDE_PLUGIN_ROOT, so
f"{PLUGIN_ROOT}/lib/catalog.json" collapsed to /lib/catalog.json.
All four PLUGIN_ROOT usages in SKILL.md now try:
1. $CLAUDE_PLUGIN_ROOT/lib/catalog.json (if env var is set)
2. ~/.claude/plugins/marketplaces/circuitforge/plugins/buddymon/lib/catalog.json
3. ~/.claude/plugins/cache/circuitforge/buddymon/0.1.1/lib/catalog.json
statusline block also fixed: prefers ~/.claude/buddymon/statusline.sh
(stable user-local copy from install.sh) over plugin-relative paths.
- wounded encounters (5% strength) skip weakening Q&A and go straight
to the throw — no more 'want to throw?' prompt at 5%
- catch roll now tries sessions/<pgrp>.json first, falls back to
active.json if missing (fixes FileNotFoundError in new windows that
haven't run any tools yet)
- XP write follows the same fallback pattern
Uncommon, str=65, 90xp. Triggered by sed errors, awk failures,
truncated/0-byte files after in-place edits, backreference failures.
Inspired by sed's layer-by-layer file processing (the 'striations')
and the real incident where sed -i with a backreference wiped catalog.json.
Weakened by: dry-run preview before -i, verify output after edit.
Flavor: 'Knows every line of your file. Edited them all. Saved none.'
state.sh used SESSION_FILE for session.json (global tracking data).
Both hook handlers override SESSION_FILE to sessions/<pgrp>.json for
per-session isolation. buddymon_session_reset() at session-stop end
was writing _version:1 data INTO sessions/<pgrp>.json, leaving stale
wrong-format session files that broke buddy lookup.
Fix: rename state.sh variable to SESSION_DATA_FILE — no more collision.
Also:
- Add matcher:'*' to SessionStart and Stop hooks (CC 2.x compatibility)
- Add dead-session GC to session-start.sh (cleans up orphaned PGRP files)
- Add 5 new privacy/security bug_monsters:
LeakWraith (uncommon) — exposed credentials
CipherNull (uncommon) — weak/broken crypto (MD5, ECB, rand() for secrets)
ConsentShadow (rare) — tracking/analytics without consent (CF flagship villain)
ThrottleDemon (common) — ignored 429s and missing backoff
PrivacyLich (legendary) — GDPR/CCPA/breach debt; unkillable, only containable
session-stop.sh writes ~/.claude/buddymon/handoff.json with: buddy id,
XP earned, commit count, languages touched, caught monsters, challenge
state, any active encounter, and manual notes (for future /buddymon note).
session-start.sh reads handoff.json on next session start, injects a
'📬 From your last session' block into additionalContext, then removes
the file so it only fires once.
Closes#1 on Circuit-Forge/buddymon.
Each Claude Code session now gets its own state file at:
~/.claude/buddymon/sessions/<pgrp>.json
Contains: buddymon_id, session_xp, challenge — all session-local.
Global active.json keeps the default buddymon_id for new sessions.
/buddymon assign writes to the session file only, so assigning in one
terminal window doesn't affect other open sessions. Each window can
have its own buddy assigned independently.
SessionStart creates the session file (inheriting global default).
SessionStop reads XP from it, writes to roster, then removes it.
Evolution triggers at Lv.100 for all three starters:
Pyrobyte → 🌋 Infernus (power 40→70, catch_rate 0.45→0.55)
Debuglin → 🔬 Verifex (power 35→60, catch_rate 0.60→0.75)
Minimox → 🌑 Nullex (power 35→55, catch_rate 0.50→0.65)
/buddymon evolve: checks eligibility, shows stat preview, resets buddy
to Lv.1 in evolved form, archives old form with evolved_into marker,
carries challenges forward.
session-stop.sh now prints EVOLUTION READY banner when level hits 100
or when already eligible at session end.
Healthy → wounded: 50% per clean run (avg ~2 runs, was instant)
Wounded → fled: 35% per clean run (avg ~3 runs, was instant)
Combined expected clean runs before auto-resolve: ~5, giving the user
a realistic window to type /buddymon catch between tool calls.
catch_pending: set immediately when /buddymon catch is invoked, suppresses
auto-resolve while weakening Q&A is in progress. Cleared before catch roll
(success clears encounter, failure leaves it without the flag so auto-resolve
resumes naturally on the next clean Bash run).
wounded: first clean Bash run without catch_pending drops the encounter to 5%
strength and re-announces via UserPromptSubmit with a fleeing message. Second
clean run auto-resolves it (it fled). UserPromptSubmit now shows distinct
announcement text for wounded vs fresh encounters.
MemoryLeech now catches: malloc failures, std::bad_alloc, Java OOM,
GC overhead limit, JavaScript heap OOM, OOMKilled, oom-killer,
macOS malloc region failures.
CudaCrash is a new uncommon bug_monster (strength 65, 130 XP) for
GPU/VRAM OOM: torch.cuda.OutOfMemoryError, CUDA error: out of memory,
cuDNN/CUBLAS allocation failures, device-side assert triggered.
Adds lib/statusline.sh — a fast bash+jq status bar widget showing
active buddy, level, session XP, and any active encounter in red.
install.sh now copies the script to ~/.claude/buddymon/statusline.sh
and wires it into settings.json automatically during install.
/buddymon statusline subcommand documented in SKILL.md for manual install.
Adds LANGUAGE_TIERS with 6 tiers: discovering → familiar → comfortable
→ proficient → expert → master (thresholds: 0/50/150/350/700/1200 XP).
add_language_affinity() writes to roster.json['language_affinities'],
accumulating across sessions. Returns (leveled_up, old_tier, new_tier)
so the Edit/Write branch can fire a level-up message immediately (Edit
PostToolUse additionalContext surfaces fine).
Session-level languages_seen remains for the one-time Explorer bonus.
Roster skill view updated to show language affinity section.
Stop hook clears active.challenge after reporting it.
Start hook assigns a random challenge from the buddy's pool if none is set.
Result: fresh challenge every session, no stale repeat.
- CC Bash tool_response uses stdout/stderr keys (not output/content/text)
- Encounter detection now works — confirmed TypeGreml match via stderr
- README: clarify Thrumble is Anthropic's widget, not driveable by plugins
CC sends Bash results as {stdout, stderr, interrupted, isImage, noOutputExpected}.
Previous code guessed output/content/text — all wrong, so encounter detection
never matched. Confirmed via active.json relay debug.
Bash PostToolUse additionalContext is silently dropped by CC — encounters
are written to state but never surfaced. Fix with a two-phase approach:
- PostToolUse (Bash): detects error, writes encounter with announced:false
- UserPromptSubmit: fires on next user message, checks for unannounced
encounter, surfaces it once, marks announced:true so dedup loop breaks
Removes debug scaffolding and the format_encounter_message call from the
Bash hook (announcement is now fully owned by user-prompt-submit.py).
- Fix session-stop.sh in 0.1.0 cache to use systemMessage instead of
hookSpecificOutput (Stop hook schema doesn't support hookSpecificOutput)
- Remove debug scaffolding from post-tool-use.py
- Installer: pre-create hook_debug.log so sandbox can write to it;
uninstall now removes marketplace plugin symlink
- README: clarify extension vs mod architecture, fix cache path in
install description
Stop hook was emitting hookSpecificOutput with hookEventName=Stop,
which is not a valid hookSpecificOutput type (only PreToolUse,
PostToolUse, UserPromptSubmit are). Changed to systemMessage.
SessionStart still uses additionalContext (confirmed working).
Stale /buddymon-fight and /buddymon-catch references in session-start.sh
updated to /buddymon fight and /buddymon catch.
install.sh now creates a full circuitforge marketplace with marketplace.json
so CC can validate the plugin name against the index before loading.
Removed invalid extraKnownMarketplaces local source (only github/git valid).
- plugin.json: flatten repository to string, remove extra fields that
failed CC schema validation (caused 'Unknown skill' on reload)
- hooks.json: remove escaped quotes from command paths (matched hookify
reference implementation)
- install.sh: register 'local' marketplace in known_marketplaces.json
so CC doesn't GC the cache symlink on /reload-plugins
- 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
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 Code plugin — collectible creatures discovered through coding.
- Bug monsters spawn from error output (NullWraith, RacePhantom, ShadowBit, 11 total)
- 5 Buddymon with affinities, challenges, and evolution chains
- SessionStart hook injects active buddy + challenge into system context
- PostToolUse hook detects error patterns, new languages, and commit events
- Stop hook tallies XP and checks challenge completion
- Single /buddymon command with start/assign/fight/catch/roster subcommands
- Local state in ~/.claude/buddymon/ (roster, encounters, active, session)
