# Unity CLI Loop: Letting an AI Agent Compile, Test and Play Your Unity Project

> Unity CLI Loop wires an LLM tool such as Claude Code or Codex into a running Unity Editor through a CLI and an MCP package. It is aimed at teams who want the compile-test-inspect-fix loop to keep running without a human clicking through the Editor.

**hatayama/unity-cli-loop** — Let AI Drive Unity, from Editor to Play Mode.

- Repository: https://github.com/hatayama/unity-cli-loop
- Stars: 574 · Forks: 50
- Language: C#
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/hatayama-unity-cli-loop

## The gap Unity CLI Loop fills between an LLM tool and a live Editor

An LLM tool can write C# for Unity. It cannot, by itself, press Play, read the console, notice that a null reference fired on frame 40, and then patch the method body while the game keeps running. Unity CLI Loop exists to close that gap. The README describes the goal as letting an AI agent "compile, test, and operate your Unity project from popular LLM tools via CLI", with the loop staying autonomous inside an existing Unity project rather than a fresh template.

The intended user is an engineer who already has a Unity project and already works inside a tool such as Claude Code, Cursor, Codex, Antigravity or GitHub Copilot. The badges at the top of the README name those five. The project does not ship its own model or its own editor; it is the bridge between an agent that can call tools and a Unity Editor that can execute them.

## Four tool groups, and why the tool count is a design constraint

The README organises the capability into four ideas. First, a self-hosted development loop: the agent compiles, runs tests, reads logs, clears the console and fixes what it finds, using `compile`, `run-tests`, `get-logs`, `clear-console`, `pause-point` and `hot-reload`. Second, Editor operation: scene building, object manipulation, menu execution and UI refinement from screenshots, via `execute-dynamic-code` and `screenshot`. Third, PlayMode testing: the agent clicks buttons, drags elements, presses keys and replays recorded input, via `simulate-mouse-ui`, `simulate-mouse-input`, `simulate-keyboard`, `replay-input`, `execute-dynamic-code` and `screenshot`. Fourth, doing all of that with what the README calls a minimal set of tools.

That fourth point is the interesting one, because it is a stated trade-off rather than a feature. `execute-dynamic-code` is the escape hatch: instead of a dedicated tool per Editor action, the agent writes code that the Editor runs. Fewer tools means a smaller surface for the model to learn and fewer things to keep in sync across releases. It also means the agent's reach is bounded by what dynamic code can express, and the README does not enumerate what that excludes.

The two tools that carry the most weight for debugging are `pause-point` and `hot-reload`. The README says the agent can "pause execution at any source line without editing code and read the variables at that moment", and that method-body fixes "can be applied instantly to the running game without waiting for a recompile". Those two together are what turn a PlayMode session into something an agent can interrogate rather than just observe.

## Installing the uloop CLI and the Unity package

The Quickstart installs three things: the CLI, the Unity package and the skills. Two prerequisites are named: a Unity project on Unity 2022.3 or later, and an LLM tool that can load skills, such as Claude Code or Codex.

On macOS or Windows Git Bash, the CLI installs from a shell script:

```sh
curl -fsSL https://raw.githubusercontent.com/hatayama/unity-cli-loop/main/scripts/install.sh | sh
```

Windows PowerShell uses a separate script:

```powershell
irm https://raw.githubusercontent.com/hatayama/unity-cli-loop/main/scripts/install.ps1 | iex
```

macOS also has a Homebrew tap:

```bash
brew install hatayama/tap/uloop
```

Verify the install with `uloop -v`. The README states the install succeeded when the first line shows the CLI version, giving `3.0.1` as the example. That version string is an example from the README, not a claim about the current release.

Next, from the root of your Unity project, install the package:

```bash
uloop package install
```

According to the README, this adds the OpenUPM scoped registry and the `io.github.hatayama.uloopmcp` dependency to `Packages/manifest.json`. A `--version <x.y.z>` flag pins a specific version. Then bring Unity up:

```bash
uloop launch
```

If Unity is already running, the README says this focuses that window instead of starting a second instance. The README notes that everything can also be installed from the Unity UI, and that either path is complete on its own.

## The V2 to V3 upgrade is the sharp edge

The README's own warning block is the most useful part of it. If a project has custom tools written against the V2 API, compile errors appear immediately after the V3 package is installed. The README calls this expected and tells you not to fix it by hand. Instead, choose `Ignore` in Unity's Safe Mode prompt on startup, then press Migrate in the migration window that opens automatically under `Window > Unity CLI Loop > Custom Tool Migration`.

Projects with no custom tools have a much shorter path: the README says everyone else migrates just by updating the package and the CLI. So the upgrade cost is not uniform. It scales with how much C# custom tooling and how many skills or scripts call the `uloop` command.

V3 also changes the runtime shape. The release notes referenced in the README describe no Node.js setup and no port management, new `hot-reload` and `pause-point` tools, automatic CLI updates with per-project version selection, and improved connection stability. That per-project version selection matters for teams: it means two Unity projects on one machine can sit on different CLI versions, which is what you want when one project is mid-migration and another is not.

## Where Unity CLI Loop is the wrong tool

The constraint that will disqualify most readers is the Unity version floor. Unity 2022.3 or later is stated as a prerequisite, and nothing in the README suggests a compatibility path for older editors. If your project is pinned to an earlier LTS line, this is not a tool you can evaluate on that project at all.

The second constraint is the trust boundary. `execute-dynamic-code` and menu execution mean the agent is not limited to reading files in your repository. It can drive the Editor. The README does not document a permission model, an allowlist or an approval step for those tools, and it does not document rollback for an Editor operation the agent performed. If you need a reviewed, human-approved change before it touches a scene, this design is the opposite of what you want.

The third is the shape of the work. Unity CLI Loop targets interactive, stateful loops against a live Editor. If what you actually need is a headless batch job that builds a player on a CI machine and exits, the PlayMode simulation and screenshot tools are dead weight, and the Editor-attached model is a worse fit than a plain command-line build invocation.

Finally, note what the README leaves open. It does not document rollback for hot-reloaded method bodies, and it does not describe what happens to a paused session if the connection drops. Those are the questions to ask before relying on `pause-point` during a long debugging run.

## Compared with Unity's own MCP server

The obvious alternative is Unity's official MCP server, which also exposes Editor capabilities to an LLM client over the Model Context Protocol. The difference is in what each side optimises for. Unity's server is maintained by the engine vendor and is tied to the Unity release cycle; Unity CLI Loop is a third-party MIT project whose README frames the design around AI-driven development loops specifically, with `pause-point`, `hot-reload`, input replay and screenshot-driven UI work as first-class tools rather than general Editor access.

The practical consequence is version coupling. Unity CLI Loop states Unity 2022.3 or later and ships its own CLI with per-project version selection, so the tool version and the Editor version move independently. An engine-vendor server moves with the Editor. Which is better depends on whether you want to pin the agent tooling separately from the engine, or take whatever the engine ships.

A second alternative for the narrower problem is to skip the agent bridge entirely and drive Unity through its batch-mode command line from a script. That gives up `pause-point`, `hot-reload` and the simulation tools, but it also gives up the live-Editor dependency, which is often the right call for build automation.

## Licence, maintenance and what an upgrade actually costs

The project is MIT licensed, which is permissive and imposes no copyleft obligation on your project. That is the whole of the licence story the README supports; questions about bundled third-party components or about the Unity package's own terms are not answered there and would need to be checked against `LICENSE.md` and the package contents.

On maintenance, the last push to the default branch was on 2026-09-10, and the most recent release listed is v3.6.3 on the same day, with v3.6.2 the day before and a `dispatcher-v3.5.1` tag alongside. The repository is not archived. The release cadence visible in that window is tight, and the README describes automatic CLI updates with per-project version selection, which lowers the per-project cost of staying current.

The upgrade cost that is documented is the V2 to V3 migration, and it is conditional: custom C# tools written against the V2 API break at compile time and go through the migration window, while everything else moves by updating the package and the CLI. If you are starting fresh on V3, that cost does not apply to you yet, but the pattern is worth noting: the project has already shipped one breaking change to its custom-tool API, and the README treats migration tooling as part of the release.

## Conclusion

Adopt Unity CLI Loop if your team already runs Unity 2022.3 or later and an LLM tool that can load skills, and you want the compile-test-inspect-fix cycle to run from the terminal. Do not adopt it if you cannot accept an agent holding Editor operations such as menu execution and dynamic code, or if your project is pinned below Unity 2022.3. Before committing, confirm three things in your own repository: that `uloop -v` prints a version, that `uloop package install` leaves `Packages/manifest.json` in a state your team accepts, and that the V3 migration window appears and completes if you have custom tools written against the V2 API.

## FAQ

### How do I install the Unity CLI Loop CLI?

On macOS or Windows Git Bash, the README gives a curl command that pipes the install script to sh; Windows PowerShell uses an irm command against install.ps1. macOS also has a Homebrew tap at hatayama/tap/uloop. Verify with `uloop -v`, which should print the CLI version on the first line.

### What is Unity CLI Loop?

It is a Unity integration tool that lets an LLM tool such as Claude Code or Codex compile, test and operate a Unity project through a CLI and an MCP package. It targets Unity 2022.3 or later and is MIT licensed.

### Which LLM tools does Unity CLI Loop work with?

The README's badges name Claude Code, Cursor, Codex, Antigravity and GitHub Copilot. The stated prerequisite is an LLM tool that can load skills, such as Claude Code or Codex.

### Does Unity CLI Loop require Node.js or port configuration?

The V3 release notes referenced in the README state that V3 removes the Node.js setup and port management that earlier versions required, and adds automatic CLI updates with per-project version selection.

### What happens to my custom tools when I upgrade to Unity CLI Loop V3?

Custom tools written against the V2 API produce compile errors immediately after the V3 package is installed, which the README calls expected. Choose Ignore in Unity's Safe Mode prompt, then press Migrate in the window that opens under Window > Unity CLI Loop > Custom Tool Migration.

## Sources

- [hatayama/unity-cli-loop on GitHub](https://github.com/hatayama/unity-cli-loop)
- [Issues](https://github.com/hatayama/unity-cli-loop/issues)
- [License: MIT](https://github.com/hatayama/unity-cli-loop/blob/main/LICENSE)
- [README](https://github.com/hatayama/unity-cli-loop/blob/main/README.md)
- [Releases](https://github.com/hatayama/unity-cli-loop/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hatayama-unity-cli-loop