🏰 Claude Dungeon

Watch your Claude Code agents come alive as pixel-art heroes in a real-time dungeon.

Claude Dungeon connects to your local Claude Code sessions and visualizes every agent as an animated knight exploring a dungeon — fighting bosses when using tools, resting at the tavern, planning at the merchant shop.

Features

• Real-time visualization — heroes appear as Claude Code sessions start and disappear when they end
• 5 connected rooms — Holy Sanctuary, Dungeon Main, Boss Arena, Merchant Shop, Tavern Rest, linked by corridors with doors
• BFS pathfinding — heroes navigate through corridors using proper tile-based pathfinding, never walking through walls
• Animated sprites — knights with idle/run/attack/rest animations from a full Metroidvania asset pack
• Lord Wizard Boss — permanently resides in Boss Arena with HP bar; attacks when heroes enter fighting state
• Guardian enemy — reacts to heroes in Dungeon Main with attack animation
• Witch Merchant NPC — animated in Merchant Shop; shows item orb when heroes are shopping
• NPC facing — heroes always face toward the NPC/Boss they are interacting with
• Skills system — manage global and per-project Claude skills (~/.claude/skills/)
• Demo mode — try it without Claude Code running
• Multi-agent support — each concurrent Claude Code session gets its own hero

Quick Start

Prerequisites

• Node.js 18+
• pnpm (npm install -g pnpm)

Installation

git clone https://github.com/your-username/claude-dungeon
cd claude-dungeon
pnpm install
pnpm dev

Open http://localhost:3000.

Connect to Claude Code

Claude Dungeon watches ~/.claude/projects/ for active sessions automatically. Just start Claude Code in any project and your hero will appear within seconds.

The app detects active sessions by monitoring file modification times. Heroes disappear ~2 minutes after a session ends (or within 15 seconds if the claude process exits).

Project Structure

client/          React 19 + Tailwind 4 frontend
  src/
    components/  DungeonMap (Canvas), HeroPanel, SkillsPanel
    hooks/       useHeroSocket, useAuth
    lib/         dungeonConfig, transcriptParser
server/          Express + tRPC backend
  routers/       agents, skills
  websocket.ts   Real-time hero state management
  bridge.ts      REST API for external data push
drizzle/         Database schema & migrations
public/sprites/  Pixel art assets (Metroidvania Asset Pack)
bridge/          Local bridge script (optional, for remote servers)

How It Works

1. The server watches ~/.claude/projects/**/*.jsonl for Claude Code transcript files
2. Each active .jsonl file (modified within 5 minutes) creates a hero
3. The transcript is parsed to determine the agent's current state (idle / fighting / resting / planning)
4. State is broadcast via WebSocket to all connected browsers
5. The Canvas renderer draws heroes in the appropriate dungeon room with matching animations
6. Heroes navigate between rooms using BFS pathfinding on a tile grid — corridors are the only valid paths

State → Room Mapping

NPC Interactions

Skills Management

Claude Dungeon includes a built-in UI for managing Claude Code skills:

• View and edit global skills in ~/.claude/skills/
• View and edit per-project skills in .claude/skills/
• Create new skills with a SKILL.md editor
• Delete skills

Remote Bridge (Optional)

If you're running Claude Code on a remote server, use the included bridge script to push hero state to a hosted Claude Dungeon instance:

# Download
curl -O https://your-instance.example.com/bridge/claude-dungeon-bridge.mjs

# Run
CLAUDE_DUNGEON_SERVER=https://your-instance.example.com \
node claude-dungeon-bridge.mjs

Tech Stack

Contributing

Contributions are welcome!

Ideas for contributions:

• Sound effects (Web Audio API)
• Mobile-responsive layout
• Support for other AI coding agents (Cursor, Copilot)
• More enemy types and boss variants
• Hero level-up animations

License

MIT — see LICENSE.

Credits

• Pixel art sprites: Another Metroidvania Asset Pack Vol. 1 by the original artist
• Built with Claude by Anthropic