A library workshop

Code Dungeon

AI coders at work, drawn as a dungeon

Part I

What Code Dungeon is

Code Dungeon is a software workshop drawn as a medieval dungeon. The people at the workbenches are real AI coding agents, and each one works through the GitHub issues of a project.

You walk through it in first person. You start in a great hall. A torchlit gallery runs south from it, and off the gallery there is a chamber for each of your projects.

The great hall of Demo Keep, lit by a candle chandelier. Four coders with nothing to do sit on stools at the bar, and Wystan the Tapster stands behind it under a sign that reads Demo Keep, worked by a guild of AI coders. — Coders with nothing to do wait at the bar in the great hall; every name in these pictures comes from demo mode and is made up.

Nothing in it is pretend. Every coder you see is a real coding agent working on one of your GitHub projects. The slate on a workbench is that coder’s live screen. The notice board is the project’s real issues and pull requests. When a piece of work passes the testers, it is merged on GitHub for real.

It runs on your own computer, with your own GitHub account and your own Claude subscription. It is made by BrainIT Consulting, and it is free, under the MIT licence.

Today I’ll show it to you on the projector. You don’t need to install anything to follow along. This page is for afterwards, when you want to try it yourself.

Video · 2:23 Introduction to Code Dungeon Opens on YouTube in a new tab youtu.be/RzP2SoLmC6Q

Part II

Who’s who

There are four kinds of people in the dungeon. One of them is you.

You, the Overlord

You set the work, recruit the guild, and step in whenever you like. Your study is the room at the back left of the great hall. Your table is there, and on it is the Overlord’s ledger, where you change how the dungeon runs.

The DungeonMaster

The DungeonMaster runs the dungeon for you. When you bring in a new project, the DungeonMaster studies it and writes its QA brief. When you say what you want built, the DungeonMaster turns it into GitHub issues, hands out work that fits the project, and puts forward recruits. You write to the DungeonMaster on your scroll.

The coders

Your guild is the people who do the work. The coders pick up GitHub issues, write the change, run the project’s checks, and open a pull request. Each one works in its own git worktree, its own copy of the project on your computer, so nobody steps on anyone else’s changes.

The chamber of the project demo-keep/pixel-todo. Maud the Scribe sits at her workbench with her back to you, and the slate on an easel in front of her shows her live terminal. More workbenches stand beyond her, one marked Empty bench, and the notice board runs along the far wall. — Maud the Scribe at her bench in a chamber; the slate in front of her is her live terminal.

The testers

The testers wear aprons and work in the assay room. They test every pull request before it is merged, and they never change it. Every chamber has at least one tester, and can have up to three.

Six words you’ll hear

Chamber. One project. Every project you connect gets its own chamber off the gallery.
Notice board. On the far wall of a chamber: that project’s issues and pull requests.
Slate. The slate on an easel at each coder’s workbench. It shows that coder’s live terminal.
Assay room. Where the testers check every pull request before it is merged.
Scroll. Yours. Press P anywhere to take it out. It holds the DungeonMaster’s letters, the recruits waiting for you, and every project at a glance.
Recruit. Someone the DungeonMaster wants to add to the guild. Recruits wait on the chairs along the great hall’s east wall for your decision.

The dungeon is one level. The rust line is your way in: from the great hall, through the archway, down the gallery and into a chamber.

Part III

One job, start to finish

Work in the dungeon is GitHub issues. An issue is one job, written down. Here is the road one job takes, and you can watch every step of it on the chamber’s notice board.

The notice board of demo-keep/pixel-todo in five columns: Backlog and In progress are empty, In QA holds two pull requests, Ready to merge is empty, and Merged holds six pull requests. — The notice board: the project’s issues and pull requests, one column for each stop on the road.

1. You write a brief

In the ledger you write a project brief: what this chamber should build next. The DungeonMaster turns it into issues. They go up on the notice board in the Backlog column. You can also file an issue yourself, from the board or the ledger.

2. A coder builds it

A free coder takes the next issue and it moves to In progress. The coder works on a branch of their own, never on the main one, and finishes by opening a pull request: the change, ready to be checked.

3. A tester checks it in the assay room

The pull request moves to In QA. A free tester reads it and its issue, runs the project’s tests, and tries the change in a real browser, with screenshots. The report goes on the pull request as a comment. If it fails, it goes back to the coder who wrote it, they fix it, and it is tested again. After three failed rounds it is marked needs you.

The assay room. Gerard the Assayer, a tester, sits at his bench checking a pull request, and the slate in front of him shows the test run. A board of gauges for CPU, memory and disk hangs on the wall to the left. — Gerard the Assayer, one of the testers, checks a pull request in the assay room; his slate shows the test run.

4. It gets merged

Once it passes, it moves to Ready to merge. Auto-merge is on to begin with, so it merges itself once QA has passed and GitHub’s checks are green. If you switch auto-merge off, you read the pull request and its QA report on GitHub, then press Merge on the notice board. Then it sits in Merged. That job is done.

One job is the rust note. Follow it down the road: from your brief to the notice board, to a coder’s bench, to the assay room, and into Merged.

Part IV

What you need

Most of you won’t have these today, and that’s fine. Today you watch. This is the list to work through at home, as the guide’s Quick start gives it:

A Windows 10 or 11 computer. Linux works too; macOS has not been tried yet.
Node.js 22 or newer, from nodejs.org.
git, from git-scm.com.
A GitHub account (github.com) and the GitHub command line, from cli.github.com. Sign it in with gh auth login. Every project in the dungeon lives on GitHub.
A Claude subscription, from claude.ai. The coders run Claude Code, which comes with the dungeon; you sign it in once.
Google Chrome, from google.com/chrome, so the testers can try your app in a real browser.
A Vercel account, from vercel.com, only if you want to put your apps on the internet from the dungeon (chapter VIII).

On Windows, one command installs Node.js, git, the GitHub command line and Chrome together. It uses winget, Windows’ own installer. Run it in PowerShell or Command Prompt and accept what it asks. Leave out any you already have; for one that’s there, winget offers to update it instead. Then close the window and open a new one, so it finds them:

winget install OpenJS.NodeJS.LTS Git.Git GitHub.cli Google.Chrome

The coders work on your own Claude subscription. The plans are on claude.ai. Code Dungeon itself is free, under the MIT licence.

Part V

Try it at home

This part is for home. It isn’t part of today’s session. Code Dungeon has a demo mode, and it is the easiest way to try it. It shows fake projects and fake coders, so nothing you do in it is real. It needs only Node.js 22 or newer: no git, no GitHub and no Claude sign-in. It costs nothing. It is a good way to learn your way round before you bring in a real project. Start it with this:

npx codedungeon@latest --demo

It starts with npx, which comes with Node.js. Get Node.js from Part IV first.

The keys you’ll need

Click the view once to grab the mouse. From then on the mouse turns your head, and the small cross in the middle of the screen is what you are pointing at.

W A S D or the arrow keys: walk. Hold Shift to run.
Mouse: look around. The mouse wheel zooms in and out.
E or left click: use what the cross is on, such as a bench, the notice board or your table.
Esc: free the mouse, or close a panel.
P: your scroll.
H: help.
B: the User Guide.

The full list is in chapter X of the guide, Keys at a glance.

Part VI

Install it

Once you have everything from Part IV, you install it with two commands. Open PowerShell anywhere. Command Prompt works too, and on Linux, open a terminal. Run the two commands one at a time. Each has its own Copy button.

1. Sign Claude in, once. A browser window asks you to allow it:

npx codedungeon@latest login

2. Start the dungeon. It opens in your browser at http://localhost:4417. Press Enter the dungeon:

npx codedungeon@latest

The first time, npm asks whether it may fetch codedungeon. Answer y.

Another day, run the second command again. The dungeon runs while its window is open. To stop it, press Ctrl + C in that window. There is nothing to update: it fetches the newest version each time it starts.

Video · 2:35 Getting started Opens on YouTube in a new tab youtu.be/Mn74ZSlh78U

For the install, follow the steps above; the video shows the idea.

Things change. The guide’s Quick start always has the current steps, so if this page and the guide ever disagree, go with the guide.

If Windows stops you

PowerShell says running scripts is disabled

Windows is blocking npm’s own PowerShell helper, which it does on a new computer. Run this once, then run the command again. It lets PowerShell run scripts you have installed yourself. Command Prompt never needs it.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

On a Mac

Code Dungeon has not been tried on a Mac yet. It runs on Windows 10 and 11, and on Linux.

Part VII

Your first project

The first time you enter, a short setup asks your name, names your hold and your DungeonMaster, and brings in your first project. Your projects, your guild and your settings are kept in a folder called codedungeon-home in your home folder.

Bringing in a project

Every project must be on GitHub, because issues and pull requests are how the guild works. You can connect a project folder, connect a GitHub repo, or start a new one. A folder that isn’t on GitHub yet gets its repo straight away, then uploads what you have committed. A big project can take a while to upload, and the guild starts once it is there.

To add another project later, open the ledger on your table and press Add a project at the bottom of the Chambers & repos tab. It gets its own chamber off the gallery.

Writing a brief

A brief is what you want this chamber to build next. Write it in plain words, the way you’d explain it to a person. There are two places to write it. One is the DungeonMaster & recruits tab of the ledger, which has a project brief for each chamber. The other is a letter to the DungeonMaster on your scroll. A letter can run to 20,000 characters, so a whole project brief fits.

The DungeonMaster turns the brief into issues, and they go up on the notice board. From there it is the road in Part III.

Approving recruits

The DungeonMaster puts forward recruits, people to add to a chamber. They wait on the chairs along the great hall’s east wall. Press E on one to read their credentials, then recruit or decline. The Recruits tab of your scroll shows the same list. You can also recruit someone yourself: aim at an empty bench in a chamber and press E.

The scroll, open on the tab for Mortimer the DungeonMaster. One of his letters puts forward a recruit, Isolde the Limner, with a Decline button and a Recruit button; the next reports what he set up in chamber 2. At the bottom is the box to write to Mortimer, with a Send button. — Your scroll: Mortimer’s letters, a recruit he puts forward, and the box where you write back.

Leave “approve every recruit” switched on

By default, every recruit waits for your yes. In the ledger’s Settings you can switch to auto-approve, up to a guild cap for each chamber. I’d leave it on approve every recruit while you’re learning. Every coder and tester is a real agent, and every agent on Claude draws on the same subscription, yours. Saying yes yourself means you always know how many are at work on your subscription.

Part VIII

When something goes wrong

Most problems show up in one of three places: the banner at the top of the screen, a message on your scroll, or the coder’s own terminal. Start there.

If something is missing, this command checks Node.js, git, the GitHub command line and the Claude sign-in, and says what to fix:

npx codedungeon@latest doctor

“GitHub CLI is not ready”

The dungeon reaches GitHub only through the GitHub command line, gh. Open a terminal and run gh auth login, then gh auth status to check. Then restart the dungeon.

Claude asks to sign in

The coders use your own Claude subscription. If a coder’s terminal is waiting at a sign-in screen, it waits for you there. Open the terminal and answer it, or run the first command from Part VI again.

A coder is stuck

Open their terminal (E on their bench) and read the last few lines. They may be waiting on a question or a slow command. Tell them what to do in the message box. Or press Stop, then ▶ Carry on to set them going again where they stopped.

The rest is in chapter IX of the guide, When something goes wrong.

At the end

Questions people ask

Is it safe? Can a coder wreck my project?

Coders never push to your main branch, and they never merge. Every change goes up as a pull request, a tester checks it, and only then does the dungeon merge it. The testers never change a pull request; they only test it. If you want the last word on every merge, switch auto-merge off in the ledger and press Merge yourself.

What does it cost?

Code Dungeon is free, under the MIT licence. The coders run on your own Claude subscription, and every one of them draws on it. The plans are on claude.ai. When Claude warns that usage is getting high, the dungeon slows itself down. To use less at once, set a Session limit in the ledger’s Settings.

Do I need to know how to code?

You write what you want built, as a brief. The DungeonMaster turns it into issues, the coders write the code, and the testers check it. You do need to install the tools in Part IV, and every project lives on GitHub, so you’ll need a GitHub account.

Does it work on a Mac?

It hasn’t been tried on a Mac yet. It runs on Windows 10 and 11, and Linux works too.

Where do I read more?

In the Code Dungeon User Guide. Inside the dungeon, press B and it opens.