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 (P), or the coder's own terminal. Start there.

"GitHub CLI is not ready"

The dungeon reaches GitHub only through the gh command. Open a terminal and run gh auth login, then gh auth status to check. Restart the dungeon afterwards. npx codedungeon@latest doctor checks Node, git, gh and the Claude login in one go (from a copy of the code, npm run doctor in its folder).

A coder waits for a permission answer

Claude Code asks before some removals, such as a folder at the top of a drive, your home folder, or the folder it works in. The dungeon answers yes only when every path being removed sits inside its own tmp folder, the scratch folder coders are told to use. Anything else waits for you: after ten minutes the coder shows needs you and your scroll says what Claude Code wants to remove. Open their terminal (E on their bench), check the path, and answer.

Claude asks to sign in

Agents use your own Claude subscription. If an agent's terminal is waiting at a sign-in or first-run screen, it waits for you there: open the terminal and answer it, or run npx codedungeon@latest login (from a copy of the code, npm run login in its folder).

Usage limits and pacing

Every agent on Claude draws on the same subscription. When Claude warns that usage is getting high, the dungeon paces itself: QA, fixes and the DungeonMaster carry on, but new issues only start while fewer sessions than Sessions while pacing (Settings, default 3) are running. Your scroll says when pacing starts and ends.

If Claude turns a session away because the limit is reached, the dungeon starts no new work until the time Claude gives, and tells you on your scroll. Sessions already running carry on. To use less at once, set a Session limit in the ledger's Settings.

A GitHub link says "Page not found"

The chamber's repository is private (the board shows private next to its GitHub link). GitHub shows a private repository's issues, pull requests and QA reports only to accounts with access, and to everyone else it says the page isn't found, as if it didn't exist. Sign in to GitHub in the browser you use for the dungeon, on the same computer, with the account the dungeon uses (its name is at the top right) or another account you've given access to the repository.

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: type in the message box, or straight into the terminal.
• Press Stop. ▶ Carry on then sets them going again where they stopped, or hand the issue to them again or to someone else. Clear bench resets a finished or failed bench.
• A failed session puts its issue back on the board; the coder gets new work after a two-minute rest. An issue that fails twice waits for you to assign it by hand. Until someone else takes it, ▶ Carry on on their panel sends them back to it.
• If the dungeon restarts, or your computer shuts down, while coders and testers are working, they pick up where they were by themselves once it is running again. If anyone doesn't, press ▶ Carry on on their panel.

A chamber says its main branch is not on GitHub yet

Coders start from the main branch on GitHub, so nothing can start until it is there. The chamber and its board say what to do, and the guild waits instead of failing. Usually the first upload never finished. When your project folder has the commits, press Push to GitHub on the notice (or run git push -u origin main in the folder). The notice shows how far it has got; with large files it can take a while. If it fails, the notice says why and offers Push again. Once main arrives, the notice goes and the guild starts on its own.

A chamber says its tests need a browser that isn't installed

A project's browser tests can ask for a browser this computer doesn't have yet, such as WebKit (Safari's engine) for iPad tests. When a coder or tester runs into that, the chamber says which one, with Install and the download size. Nothing downloads until you press it. It installs the exact build the project's own Playwright asks for (or the one npx fetched, when the project has none), and then every chamber can use it. Until then, coders and testers report those tests as not run, rather than passing them. If the build is already there when you press Install or Try again, the notice just goes. If the coder borrowed a Playwright from outside the project, the dungeon can't install its build: a message says so and the notice goes.

A pull request will not merge

If GitHub refuses the merge (for example, branch protection wants an approving review), your scroll gets a message and the dungeon tries again every 10 minutes. Checks still running after 30 minutes also get a message. Pull requests marked needs you have failed QA or their fixes three times: read the QA comment on GitHub and decide.

The view or the mouse misbehaves

• Can't look around: click the view once. Straight after Esc the browser refuses for about a second, so if the first click does nothing, click again. Where the mouse can never be captured, drag with the left button held.
• In a narrow window (a browser pane beside a chat, say) the line of keys along the bottom steps aside to leave room; the help (H) and chapter X list them all.
• The status pill says reconnecting: the dungeon's server is restarting or has stopped. Agents' terminals keep working through a restart.
• No sound: press M, and check the volume in the help (H). No music: press N, and check its own volume there too.