unity-agent-cli

README

One binary. Zero dependencies. Direct HTTP. No ceremony.

Installation · Quick Start · Commands · Custom Tools · Architecture

---

Why

Every other Unity integration asks you to install Python, run a WebSocket relay, write JSON-RPC configs, register tools, and manage a persistent server process.

This tool asks for none of that.

It is a single Go binary that talks to Unity over HTTP. The Unity-side connector starts automatically. You type a command. It runs. That is the entire mental model.

┌─────────────┐      HTTP      ┌─────────────────┐
│   Terminal  │ ◄────────────► │   Unity Editor  │
│  (1 binary) │   port 8090    │ (auto-starts)   │
└─────────────┘                └─────────────────┘

~800 lines of Go. ~2,300 lines of C#. Nothing else.

---

Installation

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/NotNull92/unity-agent-cli/main/install.sh | sh

Windows

irm https://raw.githubusercontent.com/NotNull92/unity-agent-cli/main/install.ps1 | iex

Or go install (any platform)

go install github.com/NotNull92/unity-agent-cli@latest

Manual — grab the binary from Releases for your platform.

---

Quick Start

1. Install the Unity Connector

Package Manager → Add package from git URL

https://github.com/NotNull92/unity-agent-cli.git?path=AgentConnector

Or add to Packages/manifest.json:

"com.notnull92.hera-agent": "https://github.com/NotNull92/unity-agent-cli.git?path=AgentConnector"

The connector starts automatically. No configuration.

2. Run Commands

# Is Unity connected?
unity-agent-cli status

# Enter play mode
unity-agent-cli editor play --wait

# Run any C# code inside Unity
unity-agent-cli exec "return EditorSceneManager.GetActiveScene().name;"

# Read console errors
unity-agent-cli console --type error

---

Commands

Command	What it does
editor	Play, stop, pause, refresh
exec	Run arbitrary C# inside Unity
console	Read, filter, clear logs
test	Run EditMode / PlayMode tests
menu	Execute any menu item by path
screenshot	Capture scene or game view
profiler	Read hierarchy, toggle recording
reserialize	Fix YAML after text edits
list	Show all tools + schemas
status	Connection & project info
update	Self-update the binary

---

The exec Command

The most powerful feature. Full runtime access. Zero boilerplate.

# Inspect anything
unity-agent-cli exec "return World.All.Count;" --usings Unity.Entities

# Modify the scene
unity-agent-cli exec "var go = new GameObject(\"Temp\"); return go.name;"

# Pipe complex code via stdin (no shell escaping)
echo '
var scene = EditorSceneManager.GetActiveScene();
return scene.GetRootGameObjects().Length;
' | unity-agent-cli exec

Because it compiles and runs real C#, you can call any Unity API, inspect ECS worlds, modify assets, or invoke internal editor utilities. No custom tool needed.

---

Custom Tools

Drop a C# class anywhere in your Editor assembly. It is discovered automatically.

using UnityCliConnector;
using Newtonsoft.Json.Linq;

[UnityCliTool(Name = "spawn", Group = "gameplay")]
public static class SpawnEnemy
{
    public class Parameters
    {
        [ToolParameter("X position", Required = true)] public float X;
        [ToolParameter("Y position", Required = true)] public float Y;
        [ToolParameter("Z position", Required = true)] public float Z;
        [ToolParameter("Prefab name", DefaultValue = "Enemy")] public string Prefab;
    }

    public static object HandleCommand(JObject args)
    {
        var p = new ToolParams(args);
        var prefab = Resources.Load<GameObject>(p.Get("prefab", "Enemy"));
        var inst = Object.Instantiate(prefab, new Vector3(p.GetFloat("x"), p.GetFloat("y"), p.GetFloat("z")), Quaternion.identity);
        return new SuccessResponse("Spawned", new { name = inst.name });
    }
}

Call it:

unity-agent-cli spawn --x 1 --y 0 --z 5 --prefab Goblin

unity-agent-cli list exposes parameter schemas so AI assistants can discover and call your tools without reading source code.

---

Architecture

┌─────────────┐         ┌─────────────────────────────┐
│   CLI Go    │         │      Unity Editor           │
│  (~800 LoC) │◄───────►│  ┌─────────────────────┐    │
│             │  HTTP   │  │   HttpServer        │    │
│ • discovers │  8090+  │  │   (localhost)       │    │
│ • sends cmd │         │  └──────────┬──────────┘    │
│ • prints    │         │             │ reflection     │
│   response  │         │  ┌──────────▼──────────┐    │
└─────────────┘         │  │   [UnityCliTool]    │    │
                        │  │   classes           │    │
                        │  └─────────────────────┘    │
                        └─────────────────────────────┘

• Stateless — every request is independent. No reconnection dance.
• Auto-discovery — scans ~/.unity-agent-cli/instances/ to find open Unity editors.
• Domain-reload safe — connector survives script recompilation and resumes automatically.
• Main-thread execution — all tool handlers run on Unity's main thread. Every API is safe.

---

Compared to MCP

	MCP Integrations	unity-agent-cli
Install	Python + uv + FastMCP + config	Single binary
Runtime deps	WebSocket relay, persistent process	None
Protocol	JSON-RPC 2.0 over stdio	Direct HTTP POST
Setup	Generate config, restart AI client	Add package, done
Domain reload	Complex reconnect logic	Stateless
Custom tools	[Attribute] pattern	Same [Attribute] pattern
Compatibility	MCP clients only	Any shell / any agent

---

Global Flags

--port <N>       # Override auto-discovery
--project <path> # Select by project path
--timeout <ms>   # HTTP timeout (default: 120s)

---

Author

Built by Victor for Hera AI Agent.

License

MIT