repos-and-dungeons

Your coding agent's session, as a live roguelike.

Folders are rooms · unread code is fog · failing tests are monsters · your agents are the party

Quick start · How it maps · The party · Timelapse · Videos · Privacy

⚡ Quick start

You need Node 20+ and Claude Code. In any repo where you use Claude Code:

npx github:dbl8005/repos-and-dungeons

A browser tab opens with your repo's dungeon, and every Claude Code session running in that repo walks in as a hero — live. The first run takes about a minute while it builds; after that it starts in seconds.

No agent running right now? Watch the built-in demo:

npx github:dbl8005/repos-and-dungeons --demo         # a small app
npx github:dbl8005/repos-and-dungeons --demo-large   # a ~2,500-file monorepo

🗺 Your repo becomes a dungeon

The map is built from your actual file tree, and it's deterministic: the same repo always gives the same dungeon.

The fog is the useful part: at a glance you can see which parts of the codebase your agent never looked at.

🧙 Meet the party

Every model gets its own Claude. And they talk: heroes comment on what they're doing in a D&D voice —

OPUS — "By Helm's beard! A bug in token.ts betrays us." HAIKU — "Architecture here's well-drawn, but whoever penned these sessions was surely mad." SLIME — "Your tests are MINE!"

Lines are written live by Haiku through your own Claude Code login (about one short call per hero every 15 seconds while active, which counts toward your plan usage), plus built-in lines for big moments. Prefer quiet? --no-narrator.

🔊 Sound is off by default. Click the speaker or press M for dungeon music and effects — the music shifts to drums while monsters are alive.

🎬 Share a timelapse

Click ▶ Timelapse to replay everything since you started, squeezed into 30 seconds — idle stretches are skipped and the camera follows the exploration. Click ⤓ Export to save it: MP4 or GIF, square (for social) or wide 15 / 30 / 60 seconds session clock, explored %, speech bubbles and a small watermark Hide folder names turns every room into "Room 1, Room 2…" before you share optional sound track Everything renders in your browser. Sessions are also recorded to ~/.repos-and-dungeons/recordings/ (private to your user).

🏰 Built for big repos

A huge monorepo still makes a readable map: at most 400 rooms — the biggest folders split first, the rest fold into alcoves room size grows with the square root of the file count only what's on screen is drawn, at three zoom levels press F for the overview with explored % per room, / to jump to any folder 100,000 files map in under a second and render at 60 fps.

🎥 Videos

🎮 Controls

repos-and-dungeons [repo-path] [--port n] [--no-open] [--no-narrator] [--demo | --demo-large]

🔒 Privacy

Everything runs on your machine.

• The server listens on 127.0.0.1 only and needs a random key in the URL.
• It reads your Claude Code transcripts (~/.claude/projects) and your file list (git ls-files) — never file contents.
• Game events keep file paths and test names only: no command text, tool output or file contents.
• The narrator sends Haiku only event kinds, cleaned file names and test counts.
• Exports render in your browser and are only saved where you download them.

⚙️ How it works

Repos & Dungeons tails Claude Code's session transcripts (no hooks or settings needed), turns each line into game events, and streams them over a WebSocket to a PixiJS renderer. The art and music are generated in code. The full design lives in docs/SPEC.md.

🧭 Roadmap

• /dungeon command as a Claude Code plugin
• Live usage-limit stamina bar
• npm release for instant npx repos-and-dungeons
• Replay past sessions
• Other agents (Codex, …)

Ideas welcome in Discussions and Issues.

🛠 Develop

npm install
npm test               # unit tests
npm run test:e2e       # browser tests (uses your GPU)
npm run build && node dist/cli.js --demo

License

MIT · Not affiliated with Anthropic; Claude is a trademark of Anthropic · All art and sound are made in code for this project.