hera-agent-unity

Measurement, not guessing — give AI hands on the live Editor.

_{One Go CLI · one C# UPM package · zero runtime dependencies · MIT.}

Install · Quick Start · Showcase · Commands · Batch · Custom Tools · Architecture · FAQ

English · 한국어

Why hera-agent-unity

LLMs don't know your project. They remember last year's Unity API and generalized patterns — and you pay that gap every week, in tokens and in time.

hera-agent-unity stands between them.

Before AI guesses your code, run it in the Editor and return the result. Before AI assumes a console error, fetch the actual log filtered by type. Before AI hypothesizes a Play Mode outcome, enter it and wait until it finishes. Before AI invents an API that doesn't exist in your Unity version, reflect on the live assembly.

No middleware. No Python, no WebSocket, no JSON-RPC. One Go binary, localhost HTTP, one C# UPM package. When Unity Editor opens, Hera is already there.

Hera responds to commands — never inferring, never assuming. It returns what your Unity is, right now, exactly as it is.

Guessing is expensive. Measurement is the command.

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

A small Go CLI, a single C# UPM package, zero runtime dependencies.

Tests, TUI, batch engine, and asset-config layer sit on top — but the engine that talks to Unity stays lean.

Showcase

A game prototype built primarily with hera-agent-unity — the AI agent drove the live Editor through Hera (scene setup, component wiring, Play Mode iteration), not blind code generation.

✨ UI Juicy Mode — UIs that feel alive, not just functional

The difference between a button that works and a button that feels good to press. Now your AI agent knows it too.

When an AI builds a UI, it gives you a button that works — and feels dead. It sits there. Nothing happens when you hover. It snaps when you click. Scores jump from 0 to 1000 in a single frame. Technically correct, emotionally flat.

Real games are full of tiny, satisfying details you feel more than notice: a button that swells when your cursor touches it, squashes when you press, and springs back with a little bounce. A popup that pops in instead of blinking into existence. A score that rolls upward. A damage number that floats up and fades. Designers call this "juice" (or game feel) — and it's usually the first thing AI-built UI is missing, because the model just doesn't think to add it.

UI Juicy Mode flips that default. Turn it on, and every time your agent creates a UI element, Hera hands it a concrete, numbers-included recipe for making that element feel alive — lifted straight from the Game UI/UX Bible. The agent then wires up the animation, sound, and feedback for you. No design brief, no back-and-forth, no "can you make it feel more polished?" — it just comes out juicy.

Dead vs. Juicy

How it works

It's guidance, not bloat. Hera doesn't bolt heavy runtime components onto your scene. Instead, the recipe rides back to the agent inside the manage_ui create response as an agent_hint — and the agent applies it through the normal manage_components / exec path. The connector stays Editor-only; your build stays clean.

// hera-agent-unity manage_ui create button --name PlayButton   (with Juicy Mode on)
{
  "instance_id": -8420,
  "agent_hint": "[Hera] UI Juicy Mode is on — make this feel alive (Game UI/UX Bible).\n
    Button feel (Normal → Hover → Press → Release):\n
      - Hover:   100% → 110%, EaseOut 0.15s, +5% brightness\n
      - Press:   → 95%, EaseOut 0.05s (immediate), −10% color\n
      - Release: 95% → 110% → 100% with Back overshoot, 0.2s; click SFX; 10ms haptic on mobile\n
      - Disabled: desaturate ~50%, opacity 60–70%, block interaction\n
    Tweening: DOTween is enabled — use rt.DOScale(1.1f, 0.15f).SetEase(Ease.OutQuad) …"
}

Every recipe is specific — exact scale percentages, easing curves, and timings in seconds — so the agent applies real values instead of guessing. There's a tailored recipe for each element type:

It adapts to your toolchain. If DOTween is enabled in Hera Settings, the recipe tells the agent to use DOScale-style tweens (the project standard) — otherwise it falls back to a coroutine/lerp approach that works in any project. And it always reminds the agent to gate strong motion behind a reduce-motion option, so juice never becomes nausea.

Turn it on

It's opt-in — off by default, one toggle away:

hera-agent-unity asset-config juicy on      # enable
hera-agent-unity asset-config juicy off     # disable

Or tick UI Juicy Mode in the Hera Settings window inside Unity. That's it — every UI element your agent builds from then on comes out alive.

Maximum output for minimum input. You say "add a play button." Your agent ships one that feels like a real game made it.

Installation

CLI

macOS / Linux

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

Windows (PowerShell)

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

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

chmod +x ./hera-agent-unity-<platform>
./hera-agent-unity-<platform> install

Unity Connector

Package Manager → Add package from git URL

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

Or add to Packages/manifest.json:

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

The connector starts automatically. No configuration. Requires Unity 6 (6000.0+).

Compatible Unity versions

Symptom of a too-old connector on Unity 6000.5+: the HeraAgent menu is missing and hera-agent-unity status reports no instance (the assembly failed to compile, so no menu items or HTTP server register). Fix: update the connector to 0.0.20+ — in Package Manager update the package, or re-resolve the git package (delete its entry from Packages/packages-lock.json and refocus the Editor) — then let Unity recompile.

Quick Start

You only ever type four commands at this CLI. Everything else — exec, editor, console, scene, batch, profiler, describe_type, … — is what your AI agent calls on your behalf once you've handed it the wheel.

# 1. Install the CLI (one-time, see Installation above)
# 2. Open Unity with the AgentConnector UPM package — the heartbeat appears

# Is Unity connected?
hera-agent-unity status

# Later, as maintenance:
hera-agent-unity update           # pull the latest CLI release
hera-agent-unity uninstall        # remove the CLI from PATH

That's the human loop — install, verify, occasionally update. The next section is where the real work happens: hand the agent a one-line trigger and it drives the rest.

Hand the Wheel to Your AI Agent

Open Claude Code, Codex, Cursor — any agent that can run a shell command. Ask:

"Check if hera-agent-unity is installed and explore its capabilities."

The agent will discover the CLI, run list, and start driving Unity.

Compatibility

hera-agent-unity is a plain CLI returning JSON. Any coding agent that can run shell commands works. The ecosystem is converging on AGENTS.md at the project root as the canonical multi-tool rules file — start there.

For multi-tool projects, the cleanest pattern is AGENTS.md as the single source plus a one-liner stub in tool-specific paths (> See AGENTS.md.). Cursor is the one exception — its .mdc files want the full body inline because the frontmatter is what makes the rule active.

One-time setup per project (strongly recommended)

Static — copy the template that matches your agent:

cp examples/rules/AGENTS.md <your-unity-project>/AGENTS.md
cp examples/rules/cursor.mdc <your-unity-project>/.cursor/rules/hera-agent-unity.mdc

Dynamic — let the CLI emit the lean rule body straight into your rules file:

# AGENTS.md / CLAUDE.md / Copilot / Continue.dev — plain markdown
hera-agent-unity doctor --agent-rules >> AGENTS.md

# Cursor — frontmatter prepended automatically
hera-agent-unity doctor --agent-rules --format cursor > .cursor/rules/hera-agent-unity.mdc

Either path locks in the core instruction and the auto-bootstrap protocol — once installed, saying "find hera-agent-unity" (or the Korean equivalent) makes the agent run doctor + status and report in one line, without asking.

Cursor note — Cursor's .mdc rule files require YAML frontmatter (description, globs, alwaysApply) or the rule is parsed but never activated. Use the template or the --format cursor flag — a plain markdown paste will silently no-op.

Commands

Grouped by what they touch. Run hera-agent-unity <cmd> --help for the full flag list of any entry, or list to inspect every registered tool (including custom ones) at runtime.

Editor & runtime

Scene & GameObjects

Assets, materials & shaders

Packages

Console, tests, capture

Introspection

Workflow

Status & maintenance

Stuck? Run hera-agent-unity doctor, or open docs/TROUBLESHOOTING.md.

What's New (post-v0.0.6 capability queue)

The five-tool queue locked-in at 2026-05-28 is complete. Each entry filled a gap where exec's csc warm-up cost or the syntactic overhead of wrapping a Unity API call in C# was too high for a clean AI agent workflow.

unity_docs — design + benchmarks (v0.0.12)

The same generic shape every "RAG-style" lookup tool has — query → keyed retrieval → minimal context back to the agent — except the data set is small enough (~10 MiB of HTML → 1.2 MiB of gzipped JSONL) that it ships inside the connector. No embedding model, no vector DB, no external API. A single Dictionary<string, Entry> carries the whole Unity 6 ScriptReference; a lazy three-layer pre-filter keeps "did you mean" suggestions cheap on miss.

Build path (one-time per Unity version, maintainer-run):

go run ./tools/build-unity-docs \
    --in  <path-to-Documentation/en> \
    --out AgentConnector/Editor/Data/unity_docs_6.0.jsonl.gz.bytes

The Go script applies the same compiled regex set the connector used to evaluate per call (h1.heading inherit, signature-CS sig-block, h3 Description, switch-link anchor, Unity version) and emits sorted JSONL. Gzip is auto-applied when the output path contains .gz. The committed artefact is what every CLI install picks up via the UPM package.

Runtime path — the connector lazy-loads the bundle the first time unity_docs is invoked, then everything is O(1) dict lookup with a Levenshtein fallback for misses:

Cold first call (gzip decompress + JSONL parse of 31,581 entries + dict + prefix-bucket build) is ~1.7 s and runs exactly once per Unity domain — domain reloads reset the state, the next call rebuilds.

The 220 – 280 ms CLI end-to-end you see in a terminal is Go binary startup + HTTP roundtrip + Unity queue dispatch — shared by every hera tool, not unique to unity_docs.

Response shape is intentionally minimal:

{ "title": "Rigidbody.mass",
  "signature": "public float mass;",
  "summary": "The mass of the rigidbody." }

~100 – 185 bytes per reply, ~33 input tokens to the agent. Down ~53 % from a verbose shape that echoed query_normalized, scriptreference_url, unity_version, etc. that the caller could already derive.

Miss-path scan uses three layered cheap pre-filters before paying for a Levenshtein DP table:

1. Prefix bucket — keys grouped by lowercase first letter (lazy, built once after EnsureLoaded). A typo missing only an internal character lands in the right bucket and scans ~1/26 of the corpus.
2. Length filter — abs(len(a) - len(b)) > maxDistance is a lower bound on the edit distance, so length-incompatible pairs are rejected without populating a DP table.
3. Bounded Levenshtein — the DP scan bails the moment a row min exceeds the budget; returns a maxDistance + 1 sentinel so the caller branches on a single comparison.

If the bucket yields zero results (first-character typo) the full key set is rescanned as a fallback — the Wigidbody row above is that path firing, and it still returns Rigidbody, Rigidbody2D within 2 ms.

exec — Runtime C#

The most powerful command. Full editor + runtime access. Zero boilerplate.

# Evaluate
hera-agent-unity exec "return Application.dataPath;"
hera-agent-unity exec "return GameObject.FindObjectsOfType<Camera>().Length;"

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

# ECS / custom assemblies
hera-agent-unity exec "return World.All.Count;" --usings Unity.Entities

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

# Or load from file
hera-agent-unity exec --file scripts/probe.cs

How it works. Code is wrapped in a static method, compiled with the system's Roslyn (csc) into a temporary DLL, loaded into a collectible AssemblyLoadContext (no leaks), invoked via reflection, and the result is JSON-serialized. Identical source code is served from an in-memory cache — warm calls skip csc entirely.

Default usings include System, System.Collections.Generic, System.IO, System.Linq, System.Reflection, System.Threading.Tasks, UnityEngine, UnityEngine.SceneManagement, UnityEditor, UnityEditor.SceneManagement, UnityEditorInternal.

Introspection — describe_type, find_method, list_assemblies

These three commands read what's actually loaded in your Unity project, not what an LLM half-remembers from its training cutoff.

# What's loaded? (skips System.* by default)
hera-agent-unity list_assemblies
hera-agent-unity list_assemblies --filter Unity.Entities

# Inspect a type — signatures + curated Unity pitfalls
hera-agent-unity describe_type UnityEditor.EditorApplication
hera-agent-unity describe_type AssetDatabase --members methods --limit 50

# Search method names across the live AppDomain
hera-agent-unity find_method Refresh --namespace UnityEditor

describe_type returns a pitfalls array alongside the schema — short, stable notes paired with Unity 6 Manual links. Coverage: Editor API, MonoBehaviour lifecycle, uGUI (Canvas, RectTransform, EventSystem, LayoutGroup, ScrollRect, Selectable, Mask, CanvasGroup, …). Each entry is { text, doc_url } so an agent gets signature + gotcha + fetchable doc in a single round-trip.

Pair with exec for a tight dry-run loop:

describe_type → write code → exec → fix → exec

Batch — Scripted Workflows

Run multi-step pipelines in a single CLI invocation. Ideal for CI, scripted automation, or large agentic plans.

hera-agent-unity batch --file workflow.json

{
  "commands": [
    { "command": "refresh_unity", "params": { "compile": "request" } },
    { "command": "exec",          "params": { "code": "return EditorSceneManager.GetActiveScene().name;" } },
    { "command": "console",       "params": { "type": "error", "lines": 10 } }
  ],
  "options": { "fail_fast": true }
}

Pipe JSON via stdin if you'd rather not write a file:

echo '{"commands":[{"command":"refresh_unity","params":{"compile":"request"}}]}' \
  | hera-agent-unity batch

--dry-run previews the plan without execution. fail_fast short-circuits on the first error and reports which step failed.

Profiler

Read the live profiler from your terminal — no UI required.

hera-agent-unity profiler enable                       # start recording
hera-agent-unity profiler hierarchy                    # top-level samples (last frame)
hera-agent-unity profiler hierarchy --depth 3          # recursive drill-down
hera-agent-unity profiler hierarchy --root PlayerLoop --depth 5
hera-agent-unity profiler hierarchy --frames 30 --min 0.5 --sort self
hera-agent-unity profiler disable                      # stop recording
hera-agent-unity profiler status
hera-agent-unity profiler clear

Custom Tools

Drop a C# class anywhere in your Editor assembly. It is discovered automatically — no registration, no codegen.

using HeraAgent;
using Newtonsoft.Json.Linq;
using UnityEngine;

[HeraTool(Name = "spawn", Group = "gameplay", Description = "Spawn a prefab at a position")]
public static class SpawnEnemy
{
    public class Parameters
    {
        [ToolParameter("X world position", Required = true)] public float  X      { get; set; }
        [ToolParameter("Y world position", Required = true)] public float  Y      { get; set; }
        [ToolParameter("Z world position", Required = true)] public float  Z      { get; set; }
        [ToolParameter("Prefab name",      Default = "Enemy")] public string Prefab { get; set; }
    }

    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:

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

Rules

• Decorate with [HeraTool]
• Expose public static object HandleCommand(JObject parameters) (instance methods also work)
• Return SuccessResponse(message, data) or ErrorResponse(message)
• Use { get; set; } properties in Parameters — fields are invisible to the schema generator
• Class name auto-converts to snake_case (SpawnEnemy → spawn_enemy); override with Name =
• Discovered on Editor start and after every script recompile
• Runs on Unity's main thread — every API is safe
• Duplicate tool names are flagged in the console; first registration wins

hera-agent-unity list exposes the parameter schema so agents can discover and call your tools without reading source.

Performance

hera-agent-unity is designed to keep token costs negligible for AI agent workflows. A recent smoke-test benchmark (v0.0.16, 7 representative scenarios) confirms the overhead stays minimal:

What drives cost: 88% of bytes are the C# code the agent writes (input), not the response. A typical exec call like return Time.time; costs 6 tokens total — the response itself is 2–3 tokens.

A full 50-scenario benchmark and the smoke-test report live in docs/benchmarks/.

Architecture

┌──────────────────┐           ┌──────────────────────────────────┐
│    CLI (Go)      │           │         Unity Editor             │
│                  │   HTTP    │                                  │
│  ┌────────────┐  │  POST     │  ┌────────────┐                  │
│  │  Discover  │──┼──/command─┼─►│ HttpServer │ (localhost:8090+)│
│  │  Instance  │  │           │  └─────┬──────┘                  │
│  └──────┬─────┘  │           │        │ ConcurrentQueue         │
│         │ read   │           │  ┌─────▼──────┐                  │
│  ┌──────▼─────┐  │           │  │  Command   │ EditorApplication│
│  │ Heartbeat  │  │           │  │  Router    │ .update           │
│  │   files    │◄─┼───write───┼──│            │ (main thread)    │
│  │ (instance) │  │           │  └─────┬──────┘                  │
│  └────────────┘  │           │        │ SemaphoreSlim(1,1)      │
│                  │           │  ┌─────▼──────┐                  │
│  ┌────────────┐  │           │  │    Tool    │ [HeraTool]       │
│  │  Backoff   │  │           │  │ Discovery  │ reflection       │
│  │  Polling   │  │           │  └─────┬──────┘                  │
│  └────────────┘  │           │  ┌─────▼──────┐                  │
│                  │           │  │  Handlers  │ exec, editor,    │
│                  │           │  │            │ test, profiler…  │
└──────────────────┘           │  └────────────┘                  │
                               └──────────────────────────────────┘

Engineered for AI agents

• Function-typed DI in Go. Command handlers receive sendFn and instanceResolver as injected functions. The resolve closure re-discovers the instance on every call, so domain reloads that rebind the HTTP port are absorbed transparently.
• Three-phase orchestration. Compile-triggering commands do waitForAlive → send → waitForReady. Polling uses a 1.5× backoff (100ms → 2s cap) — finer than the usual 2× because Unity often returns to ready faster than that.
• Compile grace period. editor refresh --compile keeps state == "compiling" pinned for 3 s so polling doesn't latch onto a stale "ready" before Unity actually starts the compile.
• Domain-reload-safe async jobs. PlayMode tests and Package Manager add / remove / embed all trigger a domain reload that destroys the in-flight HTTP listener and Request handle. Each writes its outcome to ~/.hera-agent-unity/status/{test,package}-result-*.json and the CLI polls at 500 ms. [InitializeOnLoad] hooks reattach watchers after the reload settles (and, for packages, run a verifying Client.List to reconstruct the outcome) so the result file always materialises.
• Atomic self-update. GitHub Releases → backup → rename → cleanup with rollback. Windows defers .bak deletion to a spawned PowerShell because the running .exe is locked.

Compared to MCP

Global Flags & Environment

--port <N>          # Select Unity instance by active heartbeat port
--project <path>    # Select Unity instance by project path (substring match)
--timeout <ms>      # Request timeout in ms (default: 60000)
--verbose           # Per-phase timings + progress messages to stderr
--quiet             # Suppress decorative progress messages (errors stay plain)
--debug             # Dump HTTP request / response bodies + discovery info to stderr
--compact-json      # Emit JSON without indentation — smaller payloads for AI agents
--narrate           # Force waitForAlive / waitForReady narration even on tool commands
                    # (default: narration is on only for human-target commands)

Each global flag has a HERA_AGENT_* environment-variable counterpart that the CLI reads when the flag is omitted. Setting these once in your shell profile lets you keep the flag off the command line.

FAQ

hera-agent-unity exec "return 1+1;" --csc "C:\Program Files\dotnet\sdk\8.0.100\Roslyn\bincore\csc.dll"

Projects Using Hera

Want yours listed? Open an issue or PR.

Author

Victor — Unity/C# developer, 6+ years of live-service MMORPG production. Building NoMoreRolls solo with hera-agent-unity · IndieAlchemist on YouTube.

Sponsors

hera-agent-unity is free and open source. If it saves you time or tokens, consider sponsoring.

Your support directly funds:

• New engine support (Godot, Unreal)
• Deeper agent integrations (Cursor, Windsurf, …)
• Documentation, video tutorials, sample projects

License

MIT — see LICENSE.