debuff doctor: why won't my game start?

npx debuff doctor checks a debuff project's whole setup in one pass and prints a fix for every problem it finds: Node, the debuff package versions, node_modules, debuff.config.ts, assets, saves, the files agents read and the browser that scenarios use. --fix applies the safe fixes and checks again. It never stops at the first problem, because a broken setup usually has more than one.

Here it is on a fresh project with nothing installed and its .mcp.json deleted:

◆  Node 24.15.0
◆  package.json found
■  Not installed: @debuffjp/audio, @debuffjp/core, @debuffjp/input, @debuffjp/juice, @debuffjp/cli, typescript, @debuffjp/dev, keiko
│  fix: npm install
■  A package.json script runs tsc, but TypeScript is not installed
│  fix: npm i -D typescript
■  Cannot find module '@debuffjp/cli' imported from 'debuff.config.ts'
│  fix: npm install (the config imports packages that aren't installed yet)
◆  saves.json is valid
▲  AI agents lack project context: missing .mcp.json with the debuff server
│  fix: … .mcp.json needs { "mcpServers": { "debuff": … } }
◆  Agent skills match debuff 0.20.0 (.claude/skills, .agents/skills)
◆  Browser for scenarios, fuzzing and agents: 155.0.8059.85
…

[debuff] 3 problems to fix
         --fix applies the safe fixes

■ is a problem that stops something working, ▲ is advice. Then npx debuff doctor --fix:

◇  npm install
◇  wrote .mcp.json
◆  8 packages installed
◆  debuff packages all at 0.20.0
◆  TypeScript is installed
◆  debuff.config.ts loaded
◆  AGENTS.md, CLAUDE.md and .mcp.json are set up for AI agents
…
[debuff] all set

What it checks

Check	What goes wrong without it
Node version	debuff needs Node 22 or newer
NODE_ENV in your shell	production turns dev code off under debuff dev; development makes debuff build keep it
Installed packages	missing node_modules, or installed versions that differ from package.json
One debuff version	every @debuffjp/* package must be on the same version
One copy of core	a nested second copy of @debuffjp/core gives a package its own Game
@debuffjp/dev	scenarios, fuzzing, the dev panel and agents need its dev hooks
TypeScript	a script runs tsc but it isn't installed
debuff.config.ts	it doesn't load, or exports the wrong thing
Assets	the asset pipeline fails, or warns
saves.json	it isn't valid JSON
Agent files	AGENTS.md, CLAUDE.md or .mcp.json is missing
Agent skills	the project's skills are missing, or written for another debuff version
Browser	no Chromium-based browser for scenarios, fuzzing and the MCP server
Latest version	a newer debuff is out (from 0.21)

Advice (▲) never fails the command: a missing .mcp.json or a newer release is worth knowing, not a reason to stop.

What --fix does, and what it won't

--fix only does what can't lose your work:

• installs, dedupes, and adds @debuffjp/dev or TypeScript, with whichever package manager the project's lockfile says it uses (npm, pnpm, yarn or bun);
• writes .mcp.json when there isn't one;
• writes the project's agent skills for the installed debuff version.

It never overwrites a .mcp.json that exists, since it may list other servers, and it never changes the version of a package you already depend on. To move to a newer release, npx debuff upgrade does that deliberately (from 0.21).

--live boots the game

Static checks can pass while the game still won't start. npx debuff doctor --live also starts the dev server, opens the game in the browser scenarios use, and waits for its dev hooks. If the game throws while starting, you get the error; if the hooks never appear, you get the line to add to src/main.ts.

For agents

npx debuff doctor --json prints the checks as one JSON document, and the MCP server has a doctor tool that returns the same thing. debuff's other commands point here too: when one fails because of the setup it exits 2 and ends with run npx debuff doctor, so an agent knows to check the setup rather than retry. The full set of exit codes is in What a coding agent needs from a CLI failure.

doctor exits 2 when a required check fails (1 before 0.20) and 0 otherwise.

Next time something won't start:

npx debuff doctor --fix