Unity CLI Loop

Installation

[!WARNING] The following software is required - Unity 2022.3 or later - Node.js 22.0 or later - Required for CLI execution - Install via the official site or your preferred version manager

Step 1: Install the CLI

Select Window > Unity CLI Loop > Settings. A dedicated window will open — confirm that the CLI button is highlighted in blue.

Press the Install CLI button. <img width="277" height="306" alt="1" src="https://github.com/user-attachments/assets/0e25c327-73bf-4af6-997b-eebb3c26b372" />

If you see the following display, the installation was successful. <img width="272" height="309" alt="2" src="https://github.com/user-attachments/assets/ec14f73b-53be-4435-af95-84bb9125e3e4" />

<details> <summary>To install from terminal</summary>

npm install -g uloop-cli

See uloop-cli on npm for details. </details>

Step 2: Install Skills

Select your target (Claude Code, Codex, etc.) and press the Install Skills button. <img width="272" height="306" alt="3" src="https://github.com/user-attachments/assets/492e9680-726a-425b-8bf1-e5983f4f15a5" />

<details> <summary>To install from terminal</summary>

```bash

Install for Claude Code project

uloop skills install --claude

Install for OpenAI Codex project

uloop skills install --codex

Or install globally

uloop skills install --claude --global

</details>

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

| Your Instruction | Skill Used by LLM Tools |
|---|---|
| "Launch Unity for this project" | `/uloop-launch` |
| "Fix the compile errors" | `/uloop-compile` |
| "Run the tests and tell me why they failed" | `/uloop-run-tests` + `/uloop-get-logs` |
| "Check the scene hierarchy" | `/uloop-get-hierarchy` |
| "Play the game and bring Unity to the front" | `/uloop-control-play-mode` + `/uloop-focus-window` |
| "Bulk-update prefab parameters" | `/uloop-execute-dynamic-code` |
| "Take a screenshot of Game View and adjust the UI layout" | `/uloop-screenshot` + `/uloop-execute-dynamic-code` |
| "Record my gameplay input" | `/uloop-record-input` |
| "Replay the recorded input" | `/uloop-replay-input` |


<details>
<summary>All 16 Bundled Skills</summary>

- `/uloop-launch` - Launch Unity with correct version
- `/uloop-compile` - Execute compilation
- `/uloop-get-logs` - Get console logs
- `/uloop-run-tests` - Run tests
- `/uloop-clear-console` - Clear console
- `/uloop-focus-window` - Bring Unity Editor to front
- `/uloop-get-hierarchy` - Get scene hierarchy
- `/uloop-find-game-objects` - Find GameObjects
- `/uloop-screenshot` - Capture EditorWindow
- `/uloop-simulate-mouse-ui` - Simulate mouse click, long-press, and drag on PlayMode UI elements
- `/uloop-simulate-mouse-input` - Simulate mouse input in PlayMode via Input System
- `/uloop-simulate-keyboard` - Simulate keyboard input in PlayMode via Input System
- `/uloop-record-input` - Record keyboard and mouse input during PlayMode
- `/uloop-replay-input` - Replay recorded input during PlayMode
- `/uloop-control-play-mode` - Control Play Mode
- `/uloop-execute-dynamic-code` - Execute dynamic C# code

</details>

<details>
<summary>Direct CLI Usage (Advanced)</summary>

You can also call the CLI directly without using Skills:

Launch with build target (Android, iOS, StandaloneOSX, etc.)

uloop launch -p Android

Compile and wait for Domain Reload to complete

uloop compile --wait-for-domain-reload true

1. compile - Execute Compilation

Performs AssetDatabase.Refresh() and then compiles, returning the results. Can detect errors and warnings that built-in linters cannot find. You can choose between incremental compilation and forced full compilation. With WaitForDomainReload=true, results are returned after Domain Reload completes, regardless of the ForceRecompile value.

→ Execute compile, analyze error and warning content
→ Automatically fix relevant files
→ Verify with compile again

Quickstart

8. screenshot - Take a Screenshot of EditorWindow

Take a screenshot of any EditorWindow as a PNG. Specify the window name (the text displayed in the title bar/tab) to capture. When multiple windows of the same type are open (e.g., 3 Inspector windows), all windows are saved with numbered filenames. Supports three matching modes: exact (default), prefix, and contains - all case-insensitive.

→ screenshot (WindowName: "Console")
→ Save Console window state as PNG
→ Provide visual feedback to AI

Add completion script to shell config (auto-detects shell)

uloop completion --install

Unity CLI Loop

日本語

<br>

<p align="center"> <img height="450" alt="logo-black-bg" src="https://github.com/user-attachments/assets/fca3047f-9042-4bf9-83bd-58b03f061082" /><br> <sub>(Logo inspired by Daft Punk's <i>Discovery</i> album art)</sub> </p>

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.

Note: This project was formerly known as uLoopMCP.

Tool Reference

For detailed specifications of all tools (parameters, responses, examples), see TOOL_REFERENCE.md.

Unity CLI Loop Extension Development

Unity CLI Loop enables efficient development of project-specific tools without requiring changes to the core package. The type-safe design allows for reliable custom tool implementation in minimal time. (If you ask AI, they should be able to make it for you soon ✨)

You can publish your extension tools on GitHub and reuse them across other projects. See uLoopMCP-extensions-sample for an example.

[!TIP] For AI-assisted development: Detailed implementation guides are available in .claude/rules/mcp-tools.md for tool development and .claude/rules/cli.md for CLI/Skills development. These guides are automatically loaded by Claude Code when working in the relevant directories.

[!IMPORTANT] Security Settings Project-specific tools require enabling Allow Third Party Tools in the uLoopMCP window "Security Settings". When developing custom tools that involve dynamic code execution, also consider the Dynamic Code Security Level setting.

<details> <summary>View Implementation Guide</summary>

Step 1: Create Schema Class (define parameters):

using System.ComponentModel;

public class MyCustomSchema : BaseToolSchema
{
    [Description("Parameter description")]
    public string MyParameter { get; set; } = "default_value";

    [Description("Example enum parameter")]
    public MyEnum EnumParameter { get; set; } = MyEnum.Option1;
}

public enum MyEnum
{
    Option1 = 0,
    Option2 = 1,
    Option3 = 2
}

Step 2: Create Response Class (define return data):

public class MyCustomResponse : BaseToolResponse
{
    public string Result { get; set; }
    public bool Success { get; set; }

    public MyCustomResponse(string result, bool success)
    {
        Result = result;
        Success = success;
    }

    // Required parameterless constructor
    public MyCustomResponse() { }
}

Step 3: Create Tool Class:

using System.Threading;
using System.Threading.Tasks;

[McpTool(Description = "Description of my custom tool")]  // ← Auto-registered with this attribute
public class MyCustomTool : AbstractUnityTool<MyCustomSchema, MyCustomResponse>
{
    public override string ToolName => "my-custom-tool";

    // Executed on main thread
    protected override Task<MyCustomResponse> ExecuteAsync(MyCustomSchema parameters, CancellationToken cancellationToken)
    {
        // Type-safe parameter access
        string param = parameters.MyParameter;
        MyEnum enumValue = parameters.EnumParameter;

        // Check for cancellation before long-running operations
        cancellationToken.ThrowIfCancellationRequested();

        // Implement custom logic here
        string result = ProcessCustomLogic(param, enumValue);
        bool success = !string.IsNullOrEmpty(result);

        // For long-running operations, periodically check for cancellation
        // cancellationToken.ThrowIfCancellationRequested();

        return Task.FromResult(new MyCustomResponse(result, success));
    }

    private string ProcessCustomLogic(string input, MyEnum enumValue)
    {
        // Implement custom logic
        return $"Processed '{input}' with enum '{enumValue}'";
    }
}

[!IMPORTANT] Important Notes: - Thread Safety: Tools execute on Unity's main thread, so Unity API calls are safe without additional synchronization.

Please also refer to Custom Tool Samples.

</details>

Unity CLI Loop Files

UserSettings/UnityMcpSettings.json stores per-user editor session state 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.permissions.json
> !**/.uloop/settings.tools.json
> 

This ignores auto-generated files and runtime outputs while allowing team-shared configuration to be tracked. Adjust the ! lines to match your team's needs — you can remove either line if you don't need to share that file.

Via Unity Package Manager

1. Open Unity Editor 2. Open Window > Package Manager 3. Click the "+" button 4. Select "Add package from git URL" 5. Enter the following URL:

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

If you installed via git URL before v1.0.0: The repository was renamed from uLoopMCP to unity-cli-loop in v1.0.0. Please update your manifest.json:

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

The old URL still works via GitHub redirect, but updating is recommended. OpenUPM users are not affected.

Using Scoped registry in Unity Package Manager

1. Open Project Settings window and go to Package Manager page 2. Add the following entry to the Scoped Registries list:

Name: OpenUPM
URL: https://package.openupm.com
Scope(s): io.github.hatayama.uloopmcp

1. Open Package Manager window and select OpenUPM in the My Registries section. Unity CLI Loop will be displayed.

[!NOTE] com.unity.inputsystem is now an optional dependency. Install it only if you want Input System features such as simulate-keyboard, simulate-mouse-input, record-input, replay-input, and the Recordings window. com.unity.test-framework is also optional. Install it only if you want the run-tests tool to execute Unity Test Runner.