# Building with coding agents

> How disko supports coding agents with JSON output, exit codes and AGENTS.md.

`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](/registry/cli-tokens).

## JSON output

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

```json
{
  "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](/errors).

`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](/get-started/test-rooms).

## Exit codes

| Code | Meaning                                               |
| ---- | ----------------------------------------------------- |
| 0    | success                                               |
| 1    | build or validation problems, always with `problems`  |
| 2    | usage error                                           |
| 3    | authentication or authorization failure               |
| 4    | disko or the registry is unreachable                  |
| 5    | conflict (such as `version_exists`) or quota exceeded |

## 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`](/llms.txt) indexes every page of these docs, and each page is
also served as plain Markdown at its URL plus `.md`.