🦀 Claudemon

A friendlier way to run your Claude Code agents — your crew is a bunch of pixel creatures you can actually watch work. And it's secretly a whole game.

Claudemon turns your Claude Code agents into a little crew of pixel creatures. Point one at a folder, tell it what to build, and it gets to work in your files while you follow along from its tank. Each creature is a real agent with its own personality and working style. When you want a break, one click drops you into Clawland, a top-down brawler where a tiny creature eats its way across an island.

It plugs into Claude Code (that's the one requirement). Free and open source. A little gift for the community. 🎁

🌐 Multiplayer is coming soon. A shared-world version (realms Phobos and Deimos) is already built and tested; it flips on in a future release.

<p align="center"> <img src="docs/hatch-full.gif" width="300" alt="Choosing an egg and hatching Clawde" /><br> <em>Pick an egg, watch it hatch, and meet your first agent.</em> </p>

<p align="center"> <img src="docs/idle-clawde.gif" width="120" alt="Clawde" /> <img src="docs/idle-mosskit.gif" width="120" alt="Mosskit" /> <img src="docs/idle-dunepup.gif" width="120" alt="Dunepup" /><br> <em>Clawde · Mosskit · Dunepup — three starters, a bigger roster to unlock.</em> </p>

---

What you get

• Agents you can see. An MCP server gives Claude a tank of pixel creatures. Point one at a folder, say what you want built, and watch it work — then check your files, not a chat log.
• A crew with personalities. Every creature is its own agent with a working style. Collect a roster and send whoever fits the job.
• It talks while it works. Claude voices your creature in character as it goes (toggle it off any time in Settings).
• Clawland, the game. A full single-player .io brawler, one click from the app.

Quick start

Claudemon plugs into Claude Code — that's really the only thing you need (plus Node ≥ 24). Pick whichever's easiest:

🔌 Install as a plugin (easiest)

Run these two inside Claude Code:

/plugin marketplace add OriginalName457/claudemon
/plugin install claudemon@claudemon-plugins

The MCP server registers and starts automatically — no paths, no config editing, no restart. Then say “launch Claudemon.” 🎮

🗣️ Just ask Claude

Already in Claude Code? Paste this and it installs itself — no terminal wrangling:

Install Claudemon from github.com/OriginalName457/claudemon — clone it, run npm run setup inside, then tell me to restart.

When it says so, restart Claude Code and say “launch Claudemon.” It'll open your handheld and offer to drop a desktop shortcut. 🎮

⌨️ Or run it yourself

git clone https://github.com/OriginalName457/claudemon
cd claudemon
npm run setup        # auto-detects the path + installs the Claude CLI if missing

Restart Claude Code and say “show Clawde.” Your tank opens at http://localhost:4573. That's it.

• Want the pixel pet in your terminal statusline too? npm run setup -- --statusline
• Just poking around without Claude? npm run app opens the tank window · npm run serve runs the server only.

---

🌍 Clawland — the game

<p align="center"> <img src="docs/gameplay-1.gif" width="420" alt="Clawland gameplay — foraging the jungle" /> <img src="docs/gameplay-2.gif" width="420" alt="Clawland gameplay — taking territory" /> </p>

From the app, hit 🌍 Clawland in the nav (or the big Enter Clawland button on the Tank page). Leave any time with 🏠 exit or Esc.

The loop: spawn as a hatchling, eat to grow (🐣 → 🥉 → 🥈 → 🥇), level up to unlock moves, and stand on glowing nodes to capture them — founding a clan and spreading territory against rival clans and the Corrupted. It doesn't really end; only death (or leaving) ends a run.

• Controls: WASD move · left-click attack · right-click special · Space dash · U ultra · middle-click ping teammates · M map · C stats · 👥 clan · scroll zoom.
• Per-creature progression that persists across runs — each creature levels up and earns an attribute point every 10 levels to spend permanently.
• Procedural attack VFX and synthesized sound (no audio files — it's all generated live), with a mute toggle.

---

Under the hood — the creature layer

Your starter grows as you interact with it and as Claude does real work for you.

🥚 Egg ──(3 interactions)──▶ 🫧 Blip ──(xp≥10)──▶ 🦀 Clawde ──(xp≥30)──▶ ┬─ care≥55 ─▶ 🦞 Prismshell ──▶ 👑 Aurelian
                                                                          └─ care<55 ─▶ 🦀 Rustclaw   ──▶ 👾 Voidmaw

• xp comes from interactions and from Claude calling work after real coding tasks.
• care is a rolling average of wellbeing (keep the stats up) — it decides which branch it evolves into.
• Stats (0–100, decay in real time): 🍖 fullness · 💧 hydration · ⚡ energy · ❤️ happiness.

MCP tools Claude can call: get_status · get_roster · feed · water · pet · play · rest · work · rename. The 🗣 Pet voice toggle in Settings controls whether Claude speaks in-character.

Run it without Claude

npm run app        # desktop app window (starts a server if needed)
npm run serve      # standalone tank server only, no window
npm start          # full MCP server + tank (for Claude Code)
npm run status     # print pet status
npm run reset      # reset to a fresh egg

Tuning knobs

• Decay / action strengths — src/state.js.
• Evolution thresholds — src/creatures.js.
• Clawland balance & content — web/clawland.html (and src/species.js).
• Egg art — the procedural renderer lives in web/play.html (cel-shaded, per-biome).
• Sound — web/sfx.js (procedural). VFX — web/fx-attacks.js.
• Port — CLAUDEMON_PORT. State location — CLAUDEMON_HOME.

Support

Claudemon is free and always will be. If it saved you some time or made you smile, a ⭐ on this repo (or sending it to a friend) genuinely helps — and if you want to fund new creatures, biomes, and the multiplayer server:

License

MIT — free to use, fork, and share. If you build something fun with it, I'd love to see it. 🦀