日本語

_{(Logo inspired by Daft Punk's Homework 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.

Note: This project was formerly known as uLoopMCP.

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, and capturing windows to verify UI layouts—are exposed as tools that LLMs can orchestrate.

Unity CLI Loop is built around three core ideas:

1. A self-hosted development loop where AI autonomously compiles, tests, inspects logs, and fixes issues. Uses compile, run-tests, get-logs, clear-console.
2. AI-driven Unity Editor operation—scene building, object manipulation, menu execution, and UI refinement from screenshots. Uses execute-dynamic-code, execute-menu-item, screenshot.
3. PlayMode automated testing—AI clicks buttons, drags elements, and verifies game behavior. (Currently focused on mouse simulation, with plans to expand to keyboard input, touch gestures, and more.) Uses simulate-mouse, execute-dynamic-code, screenshot.

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.

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

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

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

Press the Install CLI button.

If you see the following display, the installation was successful.

npm install -g uloop-cli

Select your target (Claude Code, Codex, etc.) and press the Install Skills button.

# 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

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

# List available tools
uloop list

# Launch Unity project with correct version
uloop launch

# Launch with build target (Android, iOS, StandaloneOSX, etc.)
uloop launch -p Android

# Kill running Unity and restart
uloop launch -r

# Execute compilation
uloop compile

# Compile and wait for Domain Reload to complete
uloop compile --wait-for-domain-reload true

# Get logs
uloop get-logs --max-count 10

# Run tests
uloop run-tests --filter-type all

# Execute dynamic code
uloop execute-dynamic-code --code 'using UnityEngine; Debug.Log("Hello from CLI!");'

# Add completion script to shell config (auto-detects shell)
uloop completion --install

# Explicitly specify shell (when auto-detection fails on Windows)
uloop completion --shell bash --install        # Git Bash / MINGW64
uloop completion --shell powershell --install  # PowerShell

# Check completion script
uloop completion

If --project-path / --port is omitted, the port is automatically selected from the Unity project detected in the current directory.

To operate multiple Unity instances from a single LLM tool, explicitly specify a project path or port:

# Specify by project path (absolute or relative)
uloop compile --project-path /Users/foo/my-unity-project
uloop compile --project-path ../other-project

# Specify by port number
uloop compile --port {target-port}

Using MCP instead of CLI

[!WARNING] MCP connection may be deprecated or removed in a future release. We recommend using the CLI instead.

You can also connect via MCP (Model Context Protocol). CLI and Skills installation is not required for MCP.

MCP Connection Steps

1. Select Window > uLoop. A dedicated window will open — press the MCP button.

2. Next, select the target IDE in the LLM Tool Settings section. Press the yellow "Configure {LLM Tool Name}" button to automatically connect to the IDE.

3. IDE Connection Verification

• For example, with Cursor, check the Tools & MCP in the settings page and find uLoopMCP. Click the toggle to enable MCP.

[!WARNING] About Windsurf Project-level configuration is not supported; only a global configuration is available.

Manual Setup (Usually Unnecessary)

[!NOTE] Usually automatic setup is sufficient, but if needed, you can manually edit the configuration file (e.g., mcp.json):

{
  "mcpServers": {
    "uLoopMCP": {
      "command": "node",
      "args": [
        "[Unity Package Path]/TypeScriptServer~/dist/server.bundle.js"
      ],
      "env": {
        "UNITY_TCP_PORT": "{port}"
      }
    }
  }
}

Path Examples:

• Via Package Manager: "/Users/username/UnityProject/Library/PackageCache/io.github.hatayama.uloopmcp@[hash]/TypeScriptServer~/dist/server.bundle.js"

[!NOTE] When installed via Package Manager, the package is placed in Library/PackageCache with a hashed directory name. Using the "Auto Configure Cursor" button will automatically set the correct path.

Multiple Unity Instance Support

[!NOTE] Multiple Unity instances can be supported by changing port numbers. Unity CLI Loop automatically assigns unused ports when starting up.

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

Filter by LogType or search target string with advanced search capabilities. You can also choose whether to include stacktrace. This allows you to retrieve logs while keeping the context small. MaxCount behavior: Returns the latest logs (tail-like behavior). When MaxCount=10, returns the most recent 10 logs. Advanced Search Features:

• Regular Expression Support: Use UseRegex: true for powerful pattern matching
• Stack Trace Search: Use SearchInStackTrace: true to search within stack traces

→ get-logs (LogType: Error, SearchText: "NullReference", MaxCount: 10)
→ get-logs (LogType: All, SearchText: "(?i).*error.*", UseRegex: true, MaxCount: 20)
→ get-logs (LogType: All, SearchText: "MyClass", SearchInStackTrace: true, MaxCount: 50)
→ Identify cause from stacktrace, fix relevant code

Executes Unity Test Runner and retrieves test results. You can set conditions with FilterType and FilterValue.

• FilterType: all (all tests), exact (individual test method name), regex (class name or namespace), assembly (assembly name)
• FilterValue: Value according to filter type (class name, namespace, etc.) Test results can be output as xml. The output path is returned so AI can read it. This is also a strategy to avoid consuming context.

→ run-tests (FilterType: exact, FilterValue: "PlayerControllerTests.TestJump")
→ Check failed tests, fix implementation to pass tests

Clear logs that become noise during log searches.

→ clear-console
→ Start new debug session

You can use UnitySearch.

→ unity-search (SearchQuery: "*.prefab")
→ List prefabs matching specific conditions
→ Identify problematic prefabs

Retrieve search providers offered by UnitySearch.

→ Understand each provider's capabilities, choose optimal search method

Retrieve menu items defined with [MenuItem("xxx")] attribute. Can filter by string specification.

Execute menu items defined with [MenuItem("xxx")] attribute.

→ Execute project-specific tools
→ Check results with get-logs

Retrieve objects and examine component parameters. Also retrieve information about currently selected GameObjects (multiple selection supported) in Unity Editor.

→ find-game-objects (RequiredComponents: ["Camera"])
→ Investigate Camera component parameters

→ find-game-objects (SearchMode: "Selected")
→ Get detailed information about currently selected GameObjects in Unity Editor (supports multiple selection)

Retrieve information about the currently active Hierarchy in nested JSON format. Works at runtime as well. Automatic File Export: Retrieved hierarchy data is always saved as JSON in {project_root}/.uloop/outputs/HierarchyResults/ directory. The response only returns the file path, minimizing token consumption even for large datasets. Selection Mode: Use UseSelection: true to get hierarchy starting from currently selected GameObject(s) in Unity Editor. Supports multiple selection - when parent and child are both selected, only the parent is used as root to avoid duplicate traversal.

→ Understand parent-child relationships between GameObjects, discover and fix structural issues
→ Regardless of scene size, hierarchy data is saved to a file and the path is returned instead of raw JSON
→ get-hierarchy (UseSelection: true)
→ Get hierarchy of currently selected GameObjects without specifying paths manually

Ensures the Unity Editor window becomes the foreground application on macOS and Windows Editor builds. Great for keeping visual feedback in sync after other apps steal focus. (Linux is currently unsupported.)

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

Control Unity Editor's Play Mode. Supports three actions: Play (start/resume), Stop, and Pause.

→ control-play-mode (Action: Play)
→ Start Play Mode to verify game behavior
→ control-play-mode (Action: Pause)
→ Pause to inspect state

Execute C# code dynamically within Unity Editor.

⚠️ Important Prerequisites To use this tool, you must install the Microsoft.CodeAnalysis.CSharp package using OpenUPM NuGet.

Name: OpenUPM
URL: https://package.openupm.com
Scope(s): org.nuget

Async support:

• You can write await in your snippet (Task/ValueTask/UniTask and any awaitable type)
• Cancellation is propagated when you pass a CancellationToken to the tool

Security Level Support: Implements 3-tier security control to progressively restrict executable code:

• Level 0 - Disabled

  • No compilation or execution allowed

• Level 1 - Restricted 【Recommended Setting】

  • All Unity APIs and .NET standard libraries are generally available
  • User-defined assemblies (Assembly-CSharp, etc.) are also accessible
  • Only pinpoint blocking of security-critical operations:
    • File deletion: File.Delete, Directory.Delete, FileUtil.DeleteFileOrDirectory
    • File writing: File.WriteAllText, File.WriteAllBytes, File.Replace
    • Network communication: All HttpClient, WebClient, WebRequest, Socket, TcpClient operations
    • Process execution: Process.Start, Process.Kill
    • Dynamic code execution: Assembly.Load*, Type.InvokeMember, Activator.CreateComInstanceFrom
    • Thread manipulation: Direct Thread, Task manipulation
    • Registry operations: All Microsoft.Win32 namespace operations
  • Safe operations are allowed:
    • File reading (File.ReadAllText, File.Exists, etc.)
    • Path operations (all Path.* operations)
    • Information retrieval (Assembly.GetExecutingAssembly, Type.GetType, etc.)
  • Use cases: Normal Unity development, automation with safety assurance

• Level 2 - FullAccess

  • All assemblies are accessible (no restrictions)
  • ⚠️ Warning: Security risks exist, use only with trusted code

→ execute-dynamic-code (Code: "GameObject cube = GameObject.CreatePrimitive(PrimitiveType.Cube); return \"Cube created\";")
→ Rapid prototype verification, batch processing automation
→ Unity API usage restricted according to security level

Simulate mouse click, long-press, and drag on PlayMode UI elements. Uses EventSystem and ExecuteEvents to dispatch pointer events directly — works independently of both old and new Input System.

Supports 6 actions: Click, LongPress, Drag (one-shot), DragStart/DragMove/DragEnd (split drag).

→ screenshot (CaptureMode: rendering, AnnotateElements: true)
→ Get element coordinates from AnnotatedElements (SimX/SimY)
→ simulate-mouse (Action: Click, X: 400, Y: 300)
→ simulate-mouse (Action: LongPress, X: 400, Y: 300, Duration: 5.0)
→ simulate-mouse (Action: Drag, FromX: 100, FromY: 500, X: 400, Y: 300)
→ simulate-mouse (Action: DragStart, X: 100, Y: 500)
→ simulate-mouse (Action: DragMove, X: 200, Y: 400, DragSpeed: 300)
→ simulate-mouse (Action: DragEnd, X: 400, Y: 300)

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

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.

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
}

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() { }
}

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}'";
    }
}

When you create a custom tool, you can create a Skill/ subfolder within the tool folder and place a SKILL.md file there. This allows LLM tools to automatically discover and use your custom tool through the Skills system.

How it works:

1. Create a Skill/ subfolder in your custom tool's folder
2. Place SKILL.md inside the Skill/ folder
3. Run uloop skills install --claude to install all skills (bundled + project)
4. LLM tools will automatically recognize your custom skill

Directory structure:

Assets/Editor/CustomTools/MyTool/
├── MyTool.cs           # Tool implementation
└── Skill/
    ├── SKILL.md        # Skill definition (required)
    └── references/     # Additional files (optional)
        └── usage.md

SKILL.md format:

---
name: uloop-my-custom-tool
description: "Description of what the tool does and when to use it."
---

# uloop my-custom-tool

Detailed documentation for the tool...

Scanned locations (searches for Skill/SKILL.md files):

• Assets/**/Editor/<ToolFolder>/Skill/SKILL.md
• Packages/*/Editor/<ToolFolder>/Skill/SKILL.md
• Library/PackageCache/*/Editor/<ToolFolder>/Skill/SKILL.md

See HelloWorld sample for a complete example.

For a more comprehensive example project, see uLoopMCP-extensions-sample.

MIT License