Building with coding agents

disko treats a coding agent as its primary user. Everything an agent needs is available from the terminal, without prompts or a browser.

AGENTS.md

npm create @disko-game writes a short AGENTS.md into every new game and room project. It covers the import rules and asset imports, the globals and disko: modules, how to run disko dev --json, and how to publish with a dry run first. Keep it in the project so agents read it.

No prompts

Every choice has a flag, and disko never waits for keyboard input. A missing required value fails immediately with exit code 2 and names the flag. The only human step, the browser sign-in, is optional: set DISKO_TOKEN to a CLI token.

JSON output

With --json, a one-shot command writes exactly one JSON object on stdout. Progress stays on stderr.

{
  "ok": true,
  "command": "publish",
  "result": {
    "reference": "gabriel/arena@1.4.2",
    "digest": "blake3:…",
    "archive_bytes": 812345,
    "package_bytes": 2400000
  }
}

A failure has error and, for build problems, problems. Each problem has code, path, line, column, a message that states the fix, and a docs link to the code's error page.

disko dev --json --no-open runs the game in a test room and writes one event per line: sign_in_required, room_ready (with the link), reload (ok with the digest, or failed with problems; the last working game keeps running), runtime_error (phase, message, stack), host_restarted and stopped. Set DISKO_TOKEN to a CLI token with the test_rooms permission to run it without a browser. See Test rooms.

Exit codes

A typical loop

1. Start npx disko dev --json --no-open in the background and share the link from room_ready with the people testing.

2. Edit the game. Each edit produces a reload event; fix every problem a failed one reports, and every runtime_error.

3. Run npx disko publish --dry-run --json and fix every problem it reports.

4. Publish with npx disko publish --visibility <visibility> --json.

Docs for agents

/llms.txt indexes every page of these docs, and each page is also served as plain Markdown at its URL plus .md.