unity-cli-loop: Letting an LLM Compile, Test and Poke a Running Unity Editor

The gap unity-cli-loop fills between an LLM agent and a live Unity Editor

Most agent workflows stop at the file system. The agent edits C# scripts, and a human switches to the Unity window to see whether the project still compiles, whether the Test Runner passes, and whether the feature actually behaves. unity-cli-loop exists to remove that handoff. The README frames the goal as letting an AI agent compile, test and operate a Unity project from LLM tools via CLI, and describes the design intent as a self-hosted development loop where the agent compiles, tests, inspects logs and fixes issues on its own. The audience is narrow and specific: developers who already run an agent that can load skills, such as Claude Code or Codex, on a project pinned to Unity 2022.3 or later. It is not a general Unity automation library and it is not a headless build tool. Everything it does assumes a Unity Editor process is available to talk to.

Four loops, a small tool surface, and a C# package behind the CLI

The README organises the capability into four ideas. The first is the compile and test loop, built from the tools compile, run-tests, get-logs, clear-console, pause-point and hot-reload. Two of those deserve attention. pause-point lets the agent halt execution at a source line without editing code and read the variables at that moment, which is a debugging affordance rather than a build one. hot-reload applies method-body fixes to the running game without waiting for a recompile, so the agent can change behaviour and observe it inside one session. The second idea is Editor operation through execute-dynamic-code and screenshot: scene building, object manipulation, menu execution and UI refinement driven by captured images. The third is PlayMode testing through simulate-mouse-ui, simulate-mouse-input, simulate-keyboard, replay-input, execute-dynamic-code and screenshot, which together let the agent click buttons, drag elements, press keys and replay recorded input. The fourth idea is stated as achieving all of this with a minimal set of tools, and the README points to a Design Philosophy section for the reasoning. The implementation language is C# and the repository is laid out as a Unity package under Packages/src, with documentation in Packages/src/Documentation~. V3 removed the Node.js setup and port management that earlier versions required, and the release notes describe automatic CLI updates with per-project version selection plus improved connection stability.

Installing the CLI, the package and the skills

The Quickstart installs three things: the CLI, the Unity package and the skills. On macOS or Windows Git Bash the CLI comes from a shell script fetched over curl, and PowerShell users run an irm pipeline against install.ps1. Homebrew users on macOS have a tap: brew install hatayama/tap/uloop. Verification is a single command, uloop -v, and the README says the install succeeded when the first line shows the CLI version, giving 3.0.1 as an example. The package step runs from the root of the Unity project: uloop package install. According to the README this adds the OpenUPM scoped registry and the io.github.hatayama.uloopmcp dependency to Packages/manifest.json, and a --version <x.y.z> flag pins a specific release. Then uloop launch starts Unity, or focuses the existing window if Unity is already running. That last detail matters for the agent loop: the CLI is expected to attach to a session that is already open rather than spinning up a fresh one each time.

The V2 to V3 migration is the sharpest edge in the project

The README carries an explicit warning for anyone upgrading. If a project has custom tools written against the V2 API, compile errors appear immediately after the V3 package is installed. The documentation states this is expected and tells you not to fix it by hand. The prescribed path is to choose Ignore in Unity's Safe Mode prompt at startup, then press Migrate in the migration window that opens automatically at Window > Unity CLI Loop > Custom Tool Migration. The README also notes that anyone who has written C# custom tools, or skills and scripts that call the uloop command, needs the migration guide, while everyone else migrates by updating the package and the CLI. That split is worth taking at face value: if your project has no V2 custom tools, the upgrade is close to mechanical. If it does, you are reading Packages/src/Documentation~/migration-v2-to-v3.md before you touch the package, because the failure mode lands as a wall of compile errors at exactly the moment you are trying to start work.

Where the tool stops: Editor sessions, skills and dynamic code

Two constraints follow from the material. The first is the Editor dependency. Every capability in the README, from compile to screenshot to input simulation, is framed as operating a Unity project through the Editor, and the launch step exists to bring that Editor up. There is no claim of a headless mode, and nothing in the supplied material describes compiling or testing without a running Editor. A CI pipeline that builds on a machine with no Editor session is therefore outside what this project advertises. The second is the client requirement. The prerequisites list a Unity project on 2022.3 or later and an LLM tool that can load skills, naming Claude Code and Codex as examples. An agent that cannot load skills is not covered by the installation path, even if it can run shell commands. A third point is structural rather than a limitation: execute-dynamic-code is the escape hatch for anything the fixed tool set does not cover, and the README lists it in two of the four core ideas. That is a deliberate design choice in favour of a small surface, but it also means the agent's reach is bounded by what dynamic code execution can do inside the Editor, which is a different trust and review question from a fixed command list.

How it differs from a plain Unity batch-mode build script

The obvious comparison is Unity's own command line batch mode, which is the standard way to compile and run tests without a human at the keyboard. The difference in approach is the direction of control. Batch mode is a one-shot invocation: you pass -batchmode and -executeMethod, Unity runs a method, writes a log and exits. It suits a build server that wants a pass or fail. unity-cli-loop keeps a live Editor session and exposes it as a set of tools an agent calls repeatedly, which is what makes pause-point, hot-reload and replay-input possible at all; none of those make sense against a process that exits after each command. The trade is that the live session is stateful. A batch build starts clean, while a long-running Editor accumulates whatever the agent has done to scenes, play state and console output, and clear-console appears in the tool list precisely because that state needs managing. If your need is a deterministic artifact on a build machine, batch mode is the better fit. If your need is an agent that iterates on behaviour inside a session, batch mode cannot express it.

Licence, releases and what maintenance looks like

The project is MIT licensed, which permits commercial and closed-source use with the usual requirement to keep the copyright and permission notice with the software. That is a statement about the licence text, not legal advice; check it against your own distribution model. On maintenance, the supplied material shows a steady release cadence: v3.6.3 and dispatcher-v3.5.1 both dated 2026-09-10, and v3.6.2 the day before, with the last push to the repository on the same day as v3.6.3. The separate dispatcher-v3.5.1 tag indicates the CLI and the Unity package are versioned independently, which is consistent with the README's mention of per-project version selection for CLI updates. That independence is the cost you carry at upgrade time: the CLI version and the package version are two things to keep in step, and the migration window exists because they can drift. The README does not state a support window or a deprecation policy for older Unity versions beyond the 2022.3 floor, so pinning with uloop package install --version <x.y.z> is the practical way to hold a known-good pair.

Editorial conclusion

Adopt unity-cli-loop if your team already drives a Unity 2022.3+ project through an agent that can load skills, and you want the agent to reach the Editor, the Test Runner and PlayMode without custom glue. Skip it if you need headless CI compilation with no Editor session, or if you are unwilling to migrate V2 custom tools. Before committing, run uloop -v to confirm the CLI version, check that uloop package install wrote io.github.hatayama.uloopmcp into Packages/manifest.json, and read Packages/src/Documentation~/migration-v2-to-v3.md if any existing tool calls the uloop command.

Official sources

1. hatayama/unity-cli-loop on GitHub
2. Issues
3. License: MIT
4. README
5. Releases