vscode dungeon crawler

Purpose: what the vscode dungeon crawler VS Code extension does, the promises it makes about your agents, and how to build and run it from source. Related: docs index, setup, contributing, changelog, CLAUDE.md.

What it does

vscode dungeon crawler adds a "Dungeon Crawler" tab to the VS Code bottom panel. The tab renders an animated 2D pixel-art dungeon crawler. Each active Claude Code agent session appears as a hero who fights through dungeon biomes while the agent works and rests at a campfire while the agent is idle. When the session ends, the hero warps out.

Features:

• Heroes follow your agents. A hero warps in when a session starts, advances down a scrolling corridor while the agent works, rests at the campfire (sitting, eating, reading, polishing, warming hands, sleeping) while it is idle, and does a victory pose and warps out when the session ends. Hero state comes only from the real session.
• Twelve classes. Warrior, Mage, Archer, Rogue, Cleric, Paladin, Necromancer, Bard, Druid, Monk, Artificer, and Berserker. A hero's class is a pure function of its session id, so it never changes. Classes are cosmetic: a look, a weapon, and a small effect. Necromancer, Druid, and Artificer are joined by a decorative skeleton, wolf, or turret. See classes.
• Ten stages, fifty enemies, ten bosses. Forgotten Cellar, Goblin Mine Shafts, Toxic Slime Caverns, Ancient Catacombs, Enchanted Forest Ruins, Molten Core, Frozen Citadel, Shadow Realm, Dragon's Lair, and Void Spire. After 30 kills (configurable) a stage boss walks in; defeating it fades to the next stage. After Stage 10 the loop restarts at Stage 1 as New Game+ with tougher enemies. See enemies and stages.
• Progress and achievements. The current stage and a few counters are saved in VS Code's own extension storage. 21 achievement badges unlock as the party plays.
• A small HUD. Stage name, kill track toward the boss, roster, achievements, and settings panels, a party strip, and achievement toasts, all drawn on the canvas with a built-in pixel font. See UI and UX.
• Sound, off by default. Synthesized effects and stage ambience (Web Audio, no audio files). See audio design.
• Accessibility. Reduced motion, a colour-blind-safe palette, and a hidden DOM mirror so every control works from the keyboard and a screen reader. See accessibility.
• Status bar. An optional item with the working and total agent counts (counts only, no names).
• Demo mode. With no Claude Code session, simulated Sim ... agents appear so you can see the panel working.

The panel at a glance (text sketch, not to scale; the real canvas is 320x180 pixels scaled to an integer multiple):

+----------------------------------------------------------------------------+
| 9 Dragon's Lair  [kill track ||||||||.....]  (boss pip)  NG+2     (R)(T)(G)|
+----------------------------------------------------------------------------+
| alcove (campfire)      | door |   corridor (scrolls while agents work)     |
|   torch      torch                                       torch             |
|                                                   [enemy] [enemy]  [boss]  |
|    (o)  (o)                    hero  hero  ->   <- hits are cosmetic only  |
|   resting at the fire        working heroes advance and fight              |
+----------------------------------------------------------------------------+
| [class icon + state] [class icon + state] [class icon + state] ... +N      |
+----------------------------------------------------------------------------+
  ^ HUD (top), scene (middle), party strip (bottom)

To try it without a Claude Code session, set dungeonCrawler.simulator to on and dungeonCrawler.simulatorAgentCount to a number between 1 and 16: simulated Sim ... agents spawn, work, idle, and leave on their own. You can also watch the monitor in the "vscode dungeon crawler" output channel with the log level set to Trace (see observability).

Observe only

vscode dungeon crawler is a status display. It is built around a few promises:

• It never controls your agents. The extension only observes Claude Code sessions. It never writes to, signals, stops, or sends input to any process or terminal. Clicking a hero only reveals that agent's terminal.
• The panel can only ask to show a terminal. The only request the panel can send to VS Code is to reveal an agent's terminal; it can never ask VS Code to control, stop, or type into it.
• Heroes never die. Heroes have no health, mana, or gauges, and nothing in the game can hurt, stop, or remove them. A hero's state follows its real agent session, and nothing else.
• Your transcripts stay private. The extension reads Claude Code transcripts only to learn a session's id, name, state, current tool name, and timestamp. Transcript content is never stored, logged, or sent anywhere.
• Nothing extra ships. No runtime dependencies, no image or audio files. Sprites are drawn from pixel maps in code, and sound is synthesized with Web Audio.

The full list of invariants is in CLAUDE.md.

Privacy

The monitor reads Claude Code's transcript files (~/.claude/projects/<project>/<session>.jsonl) read-only and keeps exactly five facts per session: the session id, a display name, the state (spawned, working, idle, ended), the current tool name (for example Bash), and the time of the last change. The display name is your workspace folder name (or a label from the project directory name) plus the first four characters of the session id; it never comes from transcript or terminal text. Nothing else from a transcript is kept: lines are parsed and dropped in the same step, and errors are logged as codes such as EACCES, never with their text or a file path.

By default (dungeonCrawler.projectScope: "workspace") only the sessions of the folders open in the current window are read. With "all", the transcripts of every project on this machine are read and their sessions appear in every VS Code window (still five fields only). The only thing the extension stores is your game progress (the current stage and four counters: kills in the stage, total kills, bosses defeated, and cycles, plus three achievement numbers: unlocked achievements, classes seen, and the largest party), as numbers in VS Code's own extension storage; no agent, session, tool, or transcript data is stored. Nothing is sent anywhere: the five fields go only to the panel in your own VS Code window. The monitor never writes, creates, locks, or deletes a file, never follows symbolic links below the transcript directory, never reads ~/.claude/settings.json or hooks, and never types into, stops, or closes a terminal.

Configuration

All settings live under dungeonCrawler.* and apply immediately.

A session ends (its hero leaves) when its transcript file is removed, when it leaves the configured scope, or after sessionEndTimeoutMinutes of silence. Closing a terminal never ends a session.

Relocated Claude Code configuration. If you moved Claude Code's configuration directory (for example with CLAUDE_CONFIG_DIR), the extension does not read that environment variable. Set dungeonCrawler.transcriptPath in your user settings to the projects folder inside it, for example ~/my-claude-config/projects.

Palette commands

Open the Command Palette and search for "Dungeon Crawler".

None of the commands touches a Claude Code session or terminal.

Development setup

Requirements: Node 22 (see .nvmrc) and VS Code 1.90 or newer.

npm install
npm run build

Then open the folder in VS Code and press F5 ("Run vscode dungeon crawler"). In the Extension Development Host window, open the bottom panel and select the "Dungeon Crawler" tab. The full walkthrough is in setup.

Scripts

Documentation

Start at the docs index. Contribution rules are in CONTRIBUTING.md; to add a class, enemy, or stage see adding content. Known limits and how to diagnose problems: performance and observability.

License

MIT