hatayama / unity-cli-loop

Unity CLI Loop 日本語 (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**. 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, and capturing windows to verify UI layouts—are exposed as tools that LLMs can orchestrate. Unity CLI Loop is built around three core ideas: • **A self-hosted development loop where AI autonomously compiles, tests, inspects logs, and fixes issues.** Uses , , , . • **AI-driven Unity Editor operation—scene building, object manipulation, menu execution, and UI refinement from screenshots.** Uses , , . • **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 , , . https://github.com/user-attachments/assets/569a2110-7351-4cf3-8281-3a83fe181817 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 Via Unity Package Manager • Open Unity Editor • Open Window > Package Manager • Click the "+" button • Select "Add package from git URL" • Enter the following URL: > **If you installed via git URL before v1.0.0**: The repository was renamed from to in v1.0.0. Please update your : > > The old URL still works via GitHub redirect, but updating is recommended. OpenUPM users are not affected. Via OpenUPM (Recommended) Using Scoped registry in Unity Package Manager • Open Project Settings window and go to Package Manager page • Add the following entry to the Scoped Registries list: • Open Package Manager window and select OpenUPM in the My Registries section. Unity CLI Loop will be displayed. Quickstart Step 1: Install the CLI 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. To install from terminal See uloop-cli on npm for details. Step 2: Install Skills Select your target (Claude Code, Codex, etc.) and press the **Install Skills** button. To install from terminal 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" | | | "Fix the compile errors" | | | "Run the tests and tell me why they failed" | + | | "Check the scene hierarchy" | | | "Search for prefabs" | | | "Play the game and bring Unity to the front" | + | | "Bulk-update prefab parameters" | | | "Take a screenshot of Game View and adjust the UI layout" | + | All 17 Bundled Skills • - Launch Unity with correct version • - Execute compilation • - Get console logs • - Run tests • - Clear console • - Bring Unity Editor to front • - Get scene hierarchy • - Unity Search • - Get menu items • - Execute menu item • - Find GameObjects • - Capture EditorWindow • - Simulate mouse input on PlayMode UI • - Simulate keyboard input in PlayMode via Input System • - Control Play Mode • - Execute dynamic C# code • - Get search provider details Direct CLI Usage (Advanced) You can also call the CLI directly without using Skills: Shell Completion (Optional) You can install Bash/Zsh/PowerShell completion: Project Path / Port Specification If / 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: > [!NOTE] > - and cannot be used together. > - You can find the port number in each Unity's uLoopMCP Window. 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 • Select Window > uLoop. A dedicated window will open — press the **MCP** button. • 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. • 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., ): **Path Examples**: • **Via Package Manager**: > [!NOTE] > When installed via Package Manager, the package is placed in 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. Key Features Development Loop Tools • 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 , results are returned after Domain Reload completes, regardless of the value. • get-logs - Retrieve Logs Same as Unity Console Filter by LogType or search target string with advanced searc…