agents-mini-rpg

🤖 Terminal multi-agent RPG · powered by Claude Code CLI 🌲

Every running Claude Code process becomes an in-game agent.
The world freezes when no Claude is active — it literally mirrors your AI workflow in real time.

📸 Screenshots

| 🌲 Agents Aventure Mode | 🤖 Agents vs Bugs Mode | |:-:|:-:| | | | | Forest fantasy · quests · beasts | Cyber-tech · bugs scale per round |

🎬 Demo

🌲 Agents Aventure Mode

https://github.com/Mundo-Dev0ps/agents-mini-rpg/raw/main/docs/agents-aventure.mp4

🤖 Agents vs Bugs Mode

https://github.com/Mundo-Dev0ps/agents-mini-rpg/raw/main/docs/agents-vs-bugs.mp4

Tip: GitHub renderiza .mp4 raw URLs como player inline. Si prefieres embed nativo (CDN user-images.githubusercontent.com), arrastra el archivo dentro de un issue/PR y reemplaza la URL.

✨ What is this?

Terminal tile-grid RPG where your Claude Code CLI sessions are the characters.

  Claude editing a file  →  Agent moves toward resource
  Claude running Bash    →  Agent attacks a bug
  Claude spawning Task   →  Sub-agent appears on map
  Claude goes idle       →  World freezes, map dims

Connects via MCP file-bridge — real tool calls (Edit, Bash, Read, Task…) appear live in the event log. Game runs standalone without Claude too.

🎮 Features

| | | |--|--| | 🌲🤖 Two modes | Agents Aventure (forest) and Agents vs Bugs (cyber-tech) | | 🧝🧙🧚🛡️ 4 avatars per mode | Distinct stats, abilities, aura colors | | ⚔️ Round-based progression | Enemies scale, boss waves, concurrent cap, deescalate | | 📡 MCP live event log | Every Claude tool call appears in-game | | 🧠 Process-aware engine | Tick freezes when all Claude PIDs go idle | | 🔔 Input-needed alerts | Audio + blinking badge when Claude needs you | | 👁️ Observer mode | Spectate agents, no player | | 🌙 Night mode | Toggleable dim map + star overlay | | ⬆️ Agent leveling | XP → level-up → full heal + stat boost |

🌲 Agents Aventure Mode

| Icon | Avatar | Ability | |:----:|--------|---------| | 🧝 | Elf | Elven Leap — phase through terrain | | 🧙 | Wizard | Arcane Spell — remote heal on ally | | 🧚 | Fairy | Magic Flight — fly over all obstacles | | 🛡️ | Knight | Heroic Charge — pack hunt scan |

| Tier | Icons | Example names | |:----:|:-----:|---------------| | L1 | 🐺 🐯 | WildWolf, ForestSnake | | L2 | 🐻 🦍 | ShadowBeast, MossOgre | | L3 | 🦏 🐃 | RootGolem, FrostLynx | | Boss | 🐗 🦏 🦣 🦖 🐲 | Named per wave |

🤖 Agents vs Bugs Mode

| Icon | Avatar | Ability | |:----:|--------|---------| | 🤖 | Robot | Turbo-Deploy — x2 speed when BUSY | | 🛰️ | Drone | Bypass — fly over walls | | 🛡️ | Firewall | Block Packet — terrain bypass + block | | 🔧 | Debugger | Remote Patch — heals nearby allies |

| Tier | Icons | Example names | |:----:|:-----:|---------------| | L1 | 🐛 🐜 | TimeoutError, TypeError | | L2 | 👾 🦂 | RaceCondition, MemoryLeak | | L3 | 🕷️ 🦠 | SegFault, InfiniteLoop | | Boss | 🦟 🐉 🤖 👹 💀 | Named per wave |

🗺️ Map Tiles

| Tile | Agents Aventure | Bugs | Effect | |:----:|-----------|------|--------| | ❤️ | Heart | Heart | +10 HP | | 🥩 / 🔋 | Meat | Battery | Refills hunger | | ⚔️ | Weapon | Crate | ATK +1 | | 🗡️ | Rare weapon | Hammer | ATK +2 | | ➕ | Cure | Cure | Heals | | 🕳️ | Trap | Trap | −3 HP | | 💰 | Gold | Gold | Score | | 🌲 | Tree | 🧱 Wall | Obstacle | | 🪨 | Rock | 🧱 Wall | Obstacle | | 🧱 | Brick wall | Brick wall | Built via BUILD |

🚀 Quick Start

Install from npm

npm install -g agents-mini-rpg
agent-rpg

Run from source

git clone https://github.com/Mundo-Dev0ps/agents-mini-rpg.git
cd agents-mini-rpg
npm install
npm run dev        # ts-node, no build step

Terminal size: minimum 107×34, recommended 140×42.
The game shows a resize gate if your window is too small — just resize to dismiss.

On first launch: mode menu → avatar menu → game starts. Navigate with ↑/↓ ↵, back with b, quit with q. Press 1–2 in mode menu or 1–6 in avatar menu for instant selection.

⌨️ Controls

| Key | Action | |:---:|--------| | ↑ ↓ ← → | Move | | space / ↵ | Interact (attack, pick up, talk) | | a | Class ability | | r | Respawn | | p | Pause / resume | | i / tab | Inspect agent panel | | m / esc | Settings overlay | | 1–2 / 1–6 | Quick-select in mode / avatar menus | | 1–5 | Filter event log (in-game) | | s | Toggle audio | | q | Quit |

📚 Documentation

| Doc | Contents | |-----|----------| | Compatibility | Supported agents, OS, terminals, requirements, troubleshooting | | MCP Integration | Setup, hook wiring, event log filters, privacy | | Settings & CLI Flags | In-game settings, --flags, env vars, audio | | Architecture | Layer overview, design decisions, engine internals | | Release & Contributing | CI, npm publish, adding agents/classes, PR guidelines |

📄 License

MIT — © agents-mini-rpg contributors

Built with ❤️ for the Claude Code community

⭐ Star this repo if it made your AI workflow more fun!