Unity CLI Agent

Give AI coding agents a fast, structured, verifiable way to build in Unity.

Unity CLI Agent is an open-source Codex plugin and MCP server for agent-driven Unity development. It combines safe system automation with Unity's own Live Editor MCP so an agent can install Editors, inspect projects, modify and query a running scene, run tests, build players, and verify the result instead of stopping at code generation.

Important

Unity CLI and com.unity.pipeline are currently experimental. This project follows the installed CLI's authoritative --help output and provides a guarded forward-compatible command tool as the interface evolves.

What you get

• 14 structured MCP tools for Unity CLI diagnostics, Editors, modules, projects, Pipeline, live commands, C# eval, tests, builds, and batch execution.
• Unity's native unity mcp server for dynamically discovered project-specific [CliCommand] methods.
• An agent workflow skill that teaches inspect-act-verify development, correct project targeting, and when to prefer registered commands over arbitrary eval.
• Safety boundaries for destructive operations, unbounded processes, output size, timeouts, and secrets.
• A reusable build-method template for projects that do not yet expose a CLI build entrypoint.

Quick start

1. Install Unity CLI

macOS or Linux:

curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash

Windows PowerShell:

$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex

Restart your terminal, then verify:

unity --version
unity doctor

2. Install the plugin in Codex

Add this GitHub repository as a plugin marketplace, then install the plugin:

codex plugin marketplace add Gabriel0110/unity-cli-agent
codex plugin add unity-cli-agent@unity-cli-agent

Start a new Codex task after installation so the skill and MCP tools are loaded.

To update later:

codex plugin marketplace upgrade unity-cli-agent
codex plugin add unity-cli-agent@unity-cli-agent

3. Prepare a Unity project for live control

Live Editor and Player operations require Unity 6.0 or newer and Unity Pipeline:

unity auth login
cd /path/to/MyUnityProject
unity open .
unity pipeline install --project-path "$PWD"
unity pipeline list

Wait for Unity to finish importing and recompiling the package. The plugin's unity_live_status tool will then discover the connected Editor and its registered commands.

4. Ask Codex to build

Try prompts such as:

Use $build-with-unity-cli to inspect this project, run its EditMode tests,
fix the failing player movement behavior, and verify it in Play Mode.

Create a small third-person prototype in this Unity project. Use the live
Editor feedback loop, add focused tests, and produce a macOS development build.

Inspect the currently running scene and explain why the player sometimes falls
through the floor. Fix the issue and prove the collider remains enabled in Play Mode.

How it works

flowchart LR
    A["AI agent"] --> S["Unity CLI Agent MCP"]
    A --> N["Unity native MCP"]
    S --> C["Unity CLI system commands"]
    S --> P["Pipeline command and eval"]
    N --> P
    C --> I["Editors, modules, projects, tests, builds"]
    P --> E["Running Editor or development Player"]

Loading

The plugin starts two local stdio servers:

Server	Purpose
unity-cli-system	Stable typed tools, JSON/NDJSON parsing, timeouts, output bounds, and safety checks
unity-live-editor	Unity's native MCP server, which mirrors connected [CliCommand] methods as tools

The system server launches Unity with argv arrays and shell: false. It defaults to structured, non-interactive output and preserves stdout, stderr, exit codes, timing, and parsed data for the agent.

Available system tools

Tool	What it does
unity_cli_status	Check CLI availability/version or run diagnostics
unity_cli_help	Read authoritative help from the installed CLI
unity_cli_run	Guarded escape hatch for new finite CLI commands
unity_editor_install	Preview or install an Editor and modules
unity_modules_install	List, preview, or install modules
unity_project_info	List or inspect registered Unity projects
unity_project_create	Create a non-interactive project from a template
unity_pipeline	List, install, or upgrade Unity Pipeline
unity_live_status	Discover connected Editors and available commands
unity_live_command	Execute a project-defined [CliCommand]
unity_eval	Evaluate bounded C# code or an eval file on Unity's main thread
unity_build	Run a project-owned static build method
unity_test	Run EditMode or PlayMode tests with NUnit output
unity_run	Run Unity in batch mode with explicit Editor arguments

Multiple projects and custom CLI locations

Normally, the plugin finds unity on PATH and discovers the project from the current task. You can pin either value in the MCP host environment:

Variable	Purpose
UNITY_CLI_PATH	Absolute path to the Unity CLI executable
UNITY_PROJECT_PATH	Default Unity project and native MCP target
UNITY_MCP_MAX_OUTPUT_BYTES	Maximum captured bytes per stdout/stderr stream; defaults to 2 MiB

When more than one Editor is open, pass the exact projectPath to live tools. Avoid relying on fuzzy discovery for mutations.

Security model

Live C# eval has the full authority of the connected Unity process. The plugin therefore:

• requires an explicit risk acknowledgement for eval and arbitrary batch execution;
• requires confirmation for Editor/module installation, project creation, and Pipeline mutation;
• blocks secret-bearing flags such as service-account secrets, serials, PATs, proxy credentials, and Android signing passwords;
• blocks persistent shell, mcp, watch, and follow modes through finite tools;
• requires an explicit destructive override for dangerous generic commands;
• uses bounded output and process timeouts.

Keep credentials in your MCP host, CI environment, OS keyring, or secret manager. Never place keystores, passwords, service-account secrets, license material, or tokens in prompts or tool arguments.

Developing the plugin

git clone https://github.com/Gabriel0110/unity-cli-agent.git
cd unity-cli-agent/plugins/unity-cli-agent
npm ci
npm run check

npm run check runs strict TypeScript checking, the Node test suite, and the self-contained MCP bundle build. See the plugin implementation README for direct MCP-host configuration and lower-level development details.

The project is currently verified against Unity CLI 1.0.0-beta.2. Tests do not require an installed Unity Editor; the live Editor smoke test requires Unity 6.0+ and Pipeline.

Contributing

Issues, compatibility reports, command fixtures, documentation improvements, and pull requests are welcome. Read CONTRIBUTING.md before submitting changes and report security-sensitive problems using SECURITY.md.

Primary sources

• Unity CLI documentation
• Unity CLI reference
• Unity CLI release notes
• Unity Pipeline package
• Meet the Unity CLI

License

MIT