hatayama/unity-cli-loop

Unity CLI Loop – AI‑driven Unity development from the command line

What it is – A Unity package plus a small cross‑platform CLI (uloop) that lets large‑language‑model agents (Claude Code, Codex, etc.) compile, test, edit, and control a Unity project without a human touching the editor. It works by installing a per‑project “runner” that talks to an IPC server inside the Unity Editor, exposing a set of skills (e.g., /uloop-compile, /uloop-screenshot, /uloop-pause-point).

Why it matters – The usual Unity workflow requires a developer to open the editor, click Build, run tests, read logs, and manually tweak scenes. Unity CLI Loop bundles the most common steps into CLI commands that an LLM can invoke, enabling a fully‑automated development loop: compile → run tests → read logs → pause execution → hot‑reload code → verify UI via screenshots, all from a language‑model prompt.

Core capabilities (the 21 bundled skills)

Category	Skills (examples)
Development loop	`compile`, `run-tests`, `get-logs`, `clear-console`, `hot-reload`, `pause-point`
Editor automation	`launch`, `focus-window`, `get-hierarchy`, `find-game-objects`, `execute-dynamic-code`, `screenshot`, `set-game-view-size`, `record-video`
PlayMode testing	`simulate-mouse-ui`, `simulate-mouse-input`, `simulate-keyboard`, `replay-input`, `control-play-mode`

These tools are deliberately minimal; most other editor actions can be performed with execute-dynamic-code, which runs arbitrary C# snippets inside the running Unity process.

Quick start (terminal‑only)

Install the CLI – curl … | sh (macOS/Linux) or PowerShell irm … | iex. Verify with uloop -v.
Add the Unity package – run uloop package install in the project root; it injects the OpenUPM registry entry and the io.github.hatayama.uloopmcp dependency.
Launch Unity – uloop launch (focuses an already‑running editor or starts a new one).
Install LLM skills – e.g. uloop skills install --claude for Claude Code or --agents for tools that read .agents/skills.

The same steps can be performed from the Unity UI via Window > Package Manager and Window > Unity CLI Loop > Settings.

How an LLM uses it

An LLM sends a skill command as a shell instruction. Example prompt → skill mapping:

“Compile the project and tell me the errors.” → /uloop-compile
“Run the unit tests and give me the failure log.” → /uloop-run-tests + /uloop-get-logs
“Pause at line 42 of Player.cs and show variable values.” → /uloop-pause-point
“Take a screenshot of the Game view after the player spawns.” → /uloop-screenshot
“Apply this method‑body fix without a full recompile.” → /uloop-hot-reload

Because the CLI communicates over a Unix domain socket (macOS/Linux) or a named pipe (Windows), no network ports are needed and multiple Unity instances can coexist.

Extending the toolset

Developers can add custom skills by placing a Skill/SKILL.md file (or a shell script / C# snippet) in the project. The CLI loads these at startup, and any LLM that has access to the skill directory can invoke them just like the built‑in ones.

Installation notes & compatibility

Requires Unity 2022.3+.
Works with any LLM that can execute shell commands and read skill files (Claude Code, Codex, etc.).
For Claude Code, the sandbox must exclude uloop * commands (see the README’s sandbox.excludedCommands example).
V3 no longer needs Node.js; the per‑project runner is downloaded automatically and version‑pinned via .uloop/project-runner-pin.json.

License

MIT – free to use, modify, and redistribute.

Bottom line – Unity CLI Loop turns the Unity Editor into a headless, scriptable service that LLM agents can drive, making AI‑assisted game development loops practical and reproducible.