Unity CLI Loop

English | 日本語

(Logo inspired by Daft Punk's Human After All album art)  

Let an AI agent compile, test, and operate your Unity project from popular LLM tools via CLI.

Designed to keep AI-driven development loops running autonomously inside your existing Unity projects.

[!IMPORTANT]

• What’s New in V3 — no more Node.js setup or port management, the new hot-reload / pause-point tools, automatic CLI updates with per-project version selection, and improved connection stability
• Migrating Custom Tools and Skills to V3 — for anyone who has written C# custom tools, or skills and scripts that call the uloop command. Everyone else migrates just by updating the package and the CLI

Concept

Unity CLI Loop is a Unity integration tool designed so that AI can drive your Unity project forward with minimal human intervention. Tasks that humans typically handle manually — compiling, running the Test Runner, checking logs, editing scenes, capturing windows to verify UI layouts, and even operating a freshly implemented feature to confirm it actually works — can all be carried out from LLM tools.

Unity CLI Loop is built around four core ideas:

1. A self-hosted development loop where AI autonomously compiles, tests, inspects logs, and fixes issues — it can even pause execution at any source line without editing code and read the variables at that moment to pin down a cause. Method-body fixes can be applied instantly to the running game without waiting for a recompile. Uses compile, run-tests, get-logs, clear-console, pause-point, hot-reload.
2. AI-driven Unity Editor operation — scene building, object manipulation, menu execution, and UI refinement from screenshots. Uses execute-dynamic-code, screenshot.
3. PlayMode automated testing — AI clicks buttons, drags elements, presses keys, replays recorded input, and verifies game behavior. Uses simulate-mouse-ui, simulate-mouse-input, simulate-keyboard, replay-input, execute-dynamic-code, screenshot.
4. Achieving the above with a minimal set of tools. See Design Philosophy.

Demos

Each clip is a real Claude Code session driving a small voxel game through uloop. Stretches where only the terminal changes are sped up; the game plays at real speed.

Launch Unity: launch

uloop launch opens the project in the Unity version it specifies and returns once the Editor can take commands.

https://github.com/user-attachments/assets/9e1edafe-07e6-4439-862f-4bbe6ff86f0f

Add a feature and test it: compile, run-tests

Claude adds a glowing torch block, builds the project with compile, and runs the EditMode tests with run-tests. It fixes the test that fails, then checks the torch at night in Play Mode.

https://github.com/user-attachments/assets/98bba49f-1846-4b8e-9702-733207e8318f

Change code during Play Mode: hot-reload

Claude adds a double jump and applies it with hot-reload without leaving Play Mode, then presses Space with simulate-keyboard to measure the jump heights.

https://github.com/user-attachments/assets/fdba761a-b65a-4297-92f1-5cb274f4c4cf

Stop on a line and read that frame: pause-point

The first time water flows into a gap, pause-point stops the game on the line that decides a cell’s new water level and returns that frame’s local variables, fields, and call path. A watch expression then tracks the water level along the channel while the water advances one tick at a time.

https://github.com/user-attachments/assets/99ef7b4a-b32f-4e75-9aa8-9e976f7b0078

Run C# inside the game: execute-dynamic-code

execute-dynamic-code runs C# in the running game. Claude stacks ten glass blocks in front of the player, then renders a wide shot of the tower from a temporary camera.

https://github.com/user-attachments/assets/804d81bc-e019-4423-bfcd-089cd0e207c2

Capture what the game shows: screenshot

Claude finds the lake with execute-dynamic-code, moves the camera high above it, and captures the view with screenshot, then hides the HUD and takes the shot again.

https://github.com/user-attachments/assets/da9302a6-7785-4b21-affa-e6f814094c48

Read the scene: get-hierarchy, find-game-objects

get-hierarchy saves the running scene’s tree to a file, and find-game-objects reads the Player’s components.

https://github.com/user-attachments/assets/ccb960a9-fa8a-40d8-b72c-7e24e11d32c8

Press keys: simulate-keyboard

simulate-keyboard holds W through the Input System. The player walks off the bank into the lake, and a screenshot confirms the underwater view.

https://github.com/user-attachments/assets/7b7abb7c-6d87-464e-b7d7-223109c27d30

Move and click the mouse: simulate-mouse-input

simulate-mouse-input moves the mouse gradually, the way a hand would, to break three blocks and fill the hole with water.

https://github.com/user-attachments/assets/0ecf0876-8230-4b4d-b51a-fe72cf9ca4c7

Quickstart

This guide installs three things — the CLI, the Unity package, and the skills — so that your LLM tool can drive Unity. You can install everything from the terminal or from the Unity UI; either path is complete on its own.

Before you begin

Make sure you have:

• A Unity project on Unity 2022.3 or later
• An LLM tool that can load skills, such as Claude Code or Codex

[!NOTE] Upgrading from V2: if the project has custom tools written against the V2 API, compile errors appear right after the V3 package is installed. This is expected. Do not fix them by hand: choose Ignore in Unity’s Safe Mode prompt on startup, then press Migrate in the migration window that opens automatically (Window > Unity CLI Loop > Custom Tool Migration). See Migrating Custom Tools and Skills to V3 for the full procedure.

Install from the terminal

Step 1: Install the CLI

macOS, Linux (x86_64), Windows Git Bash:

On Linux, focus-window is not supported.

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

Windows PowerShell:

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

Homebrew (macOS):

brew install hatayama/tap/uloop

Check that the install worked:

uloop -v

The install succeeded when the first line shows the CLI version (for example 3.0.1).

Step 2: Install the Unity package

Run this in the root of your Unity project:

uloop package install

This adds the OpenUPM scoped registry and the io.github.hatayama.uloopmcp dependency to Packages/manifest.json. Add --version to pin a specific version.

Then launch Unity. If Unity is already running, this focuses that window instead:

uloop launch

Once Unity is up, the package is installed into the project. The next step reads the skills from the installed package.

Step 3: Install the skills

Run the command for your LLM tool in the root of your Unity project:

# Claude Code
uloop skills install --claude

# Codex and other tools that read .agents/skills
uloop skills install --agents

# Install at the root of the Git repository that contains the Unity project
uloop skills install --claude --root git

# Install globally instead of into the project
uloop skills install --claude --global

# Sync into any directory (e.g. an external skill-package store)
uloop skills install --output-dir path/to/skills

Install from the Unity UI

Step 1: Install the Unity package

In Window > Package Manager, press “+”, choose Add package from git URL, and enter:

https://github.com/hatayama/unity-cli-loop.git?path=/Packages/src

Step 2: Install the CLI

Open Window > Unity CLI Loop > Settings and press Install CLI:

You are done when the CLI version is shown and the button changes to Uninstall CLI:

Step 3: Install the skills

In the same Settings window, select your target — for example Claude Code, or Common (.agents) for Codex and other tools that read .agents/skills — and press Install Skills:

That’s it! After installing Skills, LLM tools can automatically handle instructions like these:

Configuration for Claude Code

Claude Code runs shell commands inside a sandbox, and the sandbox blocks network access by default. The IPC connection to Unity is also affected, so uloop fails with UNITY_NOT_REACHABLE (connect: operation not permitted) at the moment it tries to connect — even when Unity itself is running fine.

Add uloop * to sandbox.excludedCommands in ~/.claude/settings.json to exclude uloop commands from the sandbox:

{
  "sandbox": {
    "excludedCommands": ["uloop *"]
  }
}

The pattern is matched against the command string as typed, so invocations starting with uloop are excluded. See docs/claude-code-sandbox.md for details and measured results.

How It Works

A uloop command reaches the Unity Editor through the following chain:

• The global uloop dispatcher — the single entry point on PATH. It interprets the command and delegates it to the runner for the target project
• uloop-project-runner — the per-project runner. The version to use is determined by each project’s .uloop/project-runner-pin.json (the pin) and downloaded automatically into a per-version user cache, which is how multiple projects on different versions coexist on one machine → project runner pin details
• The IPC server inside the Unity Editor — accepts connections from the runner, executes Unity APIs, and returns the results

The connection uses no TCP ports. It goes over a Unix domain socket on macOS/Linux and a named pipe on Windows, so there is no port to configure and no port collision with other Editor instances.

Design Philosophy

Unity CLI Loop does not chase tool count. With dynamic C# code execution (execute-dynamic-code), almost any Unity Editor operation can be accomplished through a single tool.

Too many tools make it harder for AI to choose the right one. And even when tools are packaged as Skills, each tool’s description still consumes the context window. We believe keeping tools to the essential minimum is good design.

Dedicated tools exist only for operations that dynamic code execution cannot handle by nature — such as frame-spanning input simulation and screenshot capture — and for operations called so frequently in the development loop, like compile and get-logs, that generating C# code each time would waste tokens.

When you find yourself wanting a new dedicated tool, a Skill usually suffices. Write the routine operation down as SKILL.md instructions, a shell script, or a C# snippet passed to execute-dynamic-code, and the AI just invokes it. The skill body is loaded only at startup and nothing has to be regenerated per run, so the additional token cost is close to zero. See the Custom Tool Development Guide for how to build one.

Key Features

For detailed descriptions and usage examples of every tool, see the Tool Reference.

Development Loop Tools

• compile - Run compilation and return errors and warnings
• get-logs - Retrieve the same logs as the Console, filtered by type or search string
• run-tests - Run Unity Test Runner (PlayMode / EditMode)
• hot-reload - Apply method-body changes to running code instantly, without recompiling
• pause-point - Pause PlayMode at any line without editing code and read the variables at that moment

Unity Editor Automation & Discovery Tools

• clear-console - Clear the Console logs
• find-game-objects - Search scene objects and inspect components
• get-hierarchy - Retrieve the scene structure as JSON
• focus-window - Bring the Unity Editor window to the front
• screenshot - Save screenshots of EditorWindows or the Game View
• set-game-view-size - Read and set the Game View custom resolution
• game-view-mode - Show or switch the Game view tab between Game view and Device Simulator, matching its orientation, or pick the simulated device
• record-video - Record the Game View or an Editor window to MP4 (WebM on Linux) and return frame sheets and per-frame change numbers; with ffmpeg, cut frames out afterward
• control-play-mode - Play, stop, and pause Play Mode
• execute-dynamic-code - Execute dynamic C# code

PlayMode Automated Testing Tools

• simulate-mouse-ui - Simulate mouse operations on UI elements (via EventSystem)
• simulate-mouse-input - Simulate mouse input via Input System
• simulate-keyboard - Simulate keyboard input via Input System
• replay-input - Replay input recorded in the Recordings window during PlayMode

Unity CLI Loop Extension Development

Add project-specific custom tools in a type-safe way without touching the core package. Ship a Skill/SKILL.md alongside your tool and AI agents discover it automatically.

For implementation steps and how to write Skills, see the Custom Tool Development Guide.

Other

Unity CLI Loop Files

UserSettings/UnityCliLoopSettings.json stores per-user editor settings and should always remain local-only.

The .uloop/ directory at the project root stores CLI cache, tool registry, and runtime outputs. Most of its contents are local-only, but some files can optionally be git-tracked for team sharing.

[!TIP] Recommended .gitignore pattern

**/.uloop/*
!**/.uloop/settings.tools.json
!**/.uloop/settings.skills.json

This ignores auto-generated files and runtime outputs while allowing team-shared configuration to be tracked. Remove a ! line if you don’t need to share that setting (tool enable/disable preferences or the skill install location).

project-runner-pin.json does not need to be tracked: the Editor rewrites it every time it opens the project, and uloop falls back to the pin inside the installed package. Track it (add !**/.uloop/project-runner-pin.json) only if you run uloop commands that use the pinned runner in a fresh clone that has never been opened in Unity, such as on CI.

License

MIT License