An emulator built for AI agents: AGENTS.md, an MCP server that drives the game, and free CI builds per PR

Why design for agents at all

The scarce resource in this project is not ideas. It is time on real hardware and careful measurement. A coding agent can read a log, bisect a shader or write a unit test as well as anyone, but only if it can see the running game, and only if its claims are held to the same evidence as a person's. Everything below follows from those two conditions.

AGENTS.md: the rules of the tree

AGENTS.md sits at the repository root and is the brief every agent reads first. The rules that matter most:

• Ship only a measured gain on a verified scene: a tools/bench row marked valid, with its scene check passed, from a paired A/B against a baseline in the same session.
• Experiments are switches: EDEN_NX2_* environment variables, off by default, each documented in docs/switches.md in the same pull request.
• Correctness before speed: a change that can alter the image needs a scene check and a known-issues note.
• Never commit game data: no keys, firmware, game files, dumps, caches, or logs with personal details.
• Upstream first: search Lichii, then Eglantine, before writing a fix; port with credit instead of rewriting; send fixes that are not specific to integrated GPUs back upstream.

It also carries the one-command build and test scripts for Windows and Linux, a map of the source tree, and how to verify a change with and without the game. Claude Code reads it through the repository's CLAUDE.md, and other agents that look for an AGENTS.md get the same brief.

Issues an agent can finish

An agent-ready issue is written so that nobody has to ask a follow-up question: the goal, the context with file paths, an acceptance test that runs anywhere, and how to measure the result on a device. Issue #8 builds the telemetry for the frame pacing work, and #11 and #12 are boot time work. A pull request that meets the acceptance test can be reviewed on its evidence, whoever typed it.

A debug server an agent can talk to

Start the emulator with EDEN_NX2_DEBUG_SERVER=127.0.0.1:6545 and it runs a small JSON-lines server inside the process. tools/nx2/debug_mcp.py, written in Python with only the standard library, turns that server into an MCP server over stdio. The tools an agent gets:

• status, frame_times, screenshot: what is on screen, and how evenly frames arrive.
• log_tail, log_filter: read new log lines, and change the log filter without a relaunch.
• capture_frame, reject_shaders: dump one frame's passes, or reject shaders live for a bisection.
• gpu_costs: GPU time by shader, to find the expensive draw.
• input, input_sequence: press buttons and replay timed inputs to reach a spot.

Without it, bisecting a shader that draws wrong means a rebuild, a relaunch and a walk back to the spot for every step. With it, a step is one reject and one screenshot. Finding an expensive draw starts the same way: ask for GPU time by shader, then read the shader that tops the list, as in the Hyrule Field shader fix.

Add it to Claude Code from the repository root:

claude mcp add guarana-debug -- python -I tools/nx2/debug_mcp.py --server 127.0.0.1:6545

Most other MCP clients accept an entry like this one:

{
  "mcpServers": {
    "guarana-debug": {
      "command": "python",
      "args": ["-I", "tools/nx2/debug_mcp.py", "--server", "127.0.0.1:6545"]
    }
  }
}

The etiquette is short: one request at a time while someone is playing, and agents never start or stop the emulator. A person launches the game; the agent asks it questions.

The safety rules are in docs/nx2/debug-mcp.md. The server is off unless the variable is set, refuses every host but loopback, writes only under its own dump folder and names every file itself. It returns rendered pixels, log lines, frame-dump summaries and shader hashes, and it has no way to read game files, keys or firmware from disk.

Free CI builds for every pull request

Every pull request is built on GitHub's runners, on Windows with clang-cl and on Linux with GCC, with warnings treated as errors, and the tests run. The Windows build is uploaded as a test build, and a comment on the pull request links it. A tester with the game can try the change without compiling anything, and an agent's change gets built and tested even on a machine with no compiler installed. Pull requests that only touch documentation skip the build.

Measuring the same way

tools/bench runs one scene the same way on any machine through the same debug server. It checks the scene against a reference screenshot and writes one JSON row per run, with personal details scrubbed. Only rows that are valid and passed the scene check count. Agents and people use the same harness, so a number from either compares with the other.

The policy that keeps it honest

The AI policy is five rules:

1. Disclose AI help with an Assisted-by: <tool> trailer.
2. A human owns every pull request and can explain every line of it.
3. Performance claims need measured benchmark rows, not reasoning.
4. Spam pull requests are closed without review.
5. No AI-generated game assets.

Disclosure is not a mark against a contribution. Hiding it is.

Try it

Point your agent at an issue with a prompt like the one in the README:

Read AGENTS.md and docs/ARCHITECTURE.md. Take issue #<number> (label: agent-ready).
Make the smallest change that meets its acceptance criteria, add or update tests under src/tests,
and open a pull request with an "Assisted-by: <tool>" trailer and the evidence the issue asks for.

Questions people ask

Can an agent read my game files or keys through the MCP server?

No. The server returns rendered frames, log lines, frame-dump summaries and shader hashes. It has no way to read game files, keys or firmware from disk, and it listens on loopback only.

Do I need a gaming PC to contribute?

No. CI builds and tests every pull request, and testers who own the game try the linked build. A device report needs no code at all.

Which agents does it work with?

Any MCP client. The README has the Claude Code command and a JSON entry most other clients accept, and AGENTS.md is plain Markdown any agent can read. The FAQ has more.