hera-agent-unity

Low-token Unity Editor control for AI coding agents.

_{Let Codex, Claude, Cursor, Copilot, and AntiGravity inspect and change your live Unity project — no MCP setup for the default CLI path, no Python server.}

Start in 60 seconds · Install · UI systems · Commands · Full docs

_{What's new · Verification · Agent rules · FAQ}

English · 한국어

What It Is

hera-agent-unity is a low-token CLI that lets AI coding agents control a running Unity Editor.

Think of it like a remote control for the live Editor:

The AI does not need to guess from stale training data. It can inspect the real Editor, act on it, and check the result.

AI agent  ->  hera-agent-unity  ->  Unity Editor

Why It Helps

AI often makes mistakes in Unity because it cannot see your Editor.

It may guess:

• which scene is open;
• which objects exist;
• which Unity API exists in your version;
• whether Play Mode works;
• what error is in the console.

Hera fixes that by letting the AI ask Unity directly.

hera-agent-unity status
hera-agent-unity console --type error
hera-agent-unity exec "return Application.unityVersion;"
hera-agent-unity editor play --wait

No Python server. The production-default CLI path needs no MCP config or special agent plugin. CLI v0.1.0+ also includes an experimental, default-off stdio MCP adapter for intentionally configured MCP clients. See docs/MCP.md for setup and compatibility boundaries.

What's New

v0.1.3 - package-backed MCP discovery

This follow-up patch publishes the existing default-off stdio MCP adapter through the official MCP Registry without changing the Unity Connector or normal CLI path.

v0.1.1 - hardened contracts, recovery, and release evidence

This release tightens the completed CLI + optional MCP architecture without replacing its proven Unity execution core.

The normal CLI remains the production default. MCP remains optional, default-off, and stdio-only.

v0.1.0 — safe multi-Editor targeting and an optional MCP adapter

This release completes the M0-M17 adapter migration without replacing the normal CLI. MCP is shipped as an experimental, stdio-only, environment-gated option; the typed CLI and localhost Unity Connector remain the production default.

Why make this migration?

More AI applications now speak MCP as a common way to discover and call tools. Hera already had a small, efficient CLI and a proven Unity execution path, so rebuilding the product around MCP would have duplicated that work and changed a workflow that existing users rely on. Instead, v0.1.0 adds a thin translator at the edge: an MCP-capable AI can speak its familiar protocol while Hera keeps executing the same validated CLI and Connector operations underneath.

Think of the CLI as Hera's compact dedicated remote control. The MCP adapter is a small plug converter that lets a different device use that remote; it does not replace the remote with a larger control panel.

How does it work?

The path is AI client → optional MCP adapter → existing Hera execution core → localhost Connector → the selected Unity Editor. The adapter searches and describes tools, validates the requested operation, applies the same safety policy, and then hands the call to Hera's existing execution path. It does not open Unity to the network, replace the Connector, or silently relax approvals. Unsupported approval or operation-ledger features fail closed instead of guessing that an operation is safe.

Does it make Hera more accurate?

MCP by itself does not make an AI smarter, and the adapter does not use a different Unity execution engine. Accuracy improves at the delivery layer: an exact normalized project path prevents a request from drifting to another open Editor; strict live contracts reject malformed or outdated arguments; and a fresh heartbeat distinguishes a domain reload, an Editor restart, a lost target, and a port that another project has taken over. Operation IDs and the Connector ledger also prevent an uncertain response from becoming the same mutation twice.

In everyday terms, Hera now checks both the full delivery address and the receipt before acting. That reduces wrong-project calls, invalid requests, and duplicate changes. It does not guarantee that the AI's design decision is correct, replace Unity tests, or prove a numerical accuracy improvement. No repository benchmark currently supports an “X% more accurate” claim; the measurable promise is narrower: detect more ambiguous or stale connection states and stop safely instead of guessing.

The first retained end-to-end game-creation run is the Crystal Forge real-world benchmark. It reached the correct playable result only after several repairs; first attempt success was not achieved. It is a regression baseline, not an MCP-versus-CLI A/B result or proof of higher model accuracy.

Does it use more tokens?

The normal CLI path has no new token cost because it has not changed. MCP adds some unavoidable protocol metadata, so token use is not guaranteed to be identical and depends on the AI client and the task. Hera limits that overhead in two ways: Profile exposes a small, stable native surface, while Compact MCP registers only three gateway tools — search, describe, and call — and fetches a tool's details only when they are needed. The large Full surface remains an explicit diagnostic option rather than the default.

There is not yet a repository benchmark that proves exact CLI/MCP token parity. The design goal is therefore honest and narrower: preserve the CLI's current cost, and make MCP compatibility pay as little up-front context cost as possible.

Why borrow Compact MCP if Hera is CLI-first?

Hera's principle is low-token, verifiable Unity control — not loyalty to one protocol. Refusing MCP completely would isolate Hera from compatible AI hosts; adopting a conventional “register every tool” MCP design would send a large catalog of names, descriptions, and schemas into context before most of it was needed. v0.1.0 deliberately uses MCP only as the outside language and keeps the CLI as the production core. Compact exposure preserves the original philosophy by making compatibility on-demand instead of turning compatibility into a permanent token tax.

Unity De-slop Mode (Beta) — static visual discipline

Game Feel Mode covers how a screen moves. De-slop Mode covers how it sits still: the tells that make generated UI look generated. The taxonomy ships inside the connector (0.0.63 and up), so there is nothing to fetch.

Read the mode → · Game Feel Mode →

UI Toolkit scaffolding, grounded in the live Editor

Connector 0.0.61 added a first-class UI Toolkit path without asking an agent to guess version-specific APIs.

Choose a UI system → · Read the UI document contract →

Latest CLI release - v0.1.3

The latest published CLI release is v0.1.3 (August 4, 2026). Its released Unity package is Connector 0.0.80. CLI and connector versions are intentionally separate.

Release compatibility matrix:

The preceding Connector 0.0.75 also passed clean UPM import and runtime checks across the same matrix. Evidence: Unity compatibility inventory

Low-token benchmark baseline:

Full benchmark notes: docs/benchmarks/token-reduction/README.md

Quick Start

1. Open Unity

Open a Unity project that has the Hera Unity package installed.

2. Check the connection

hera-agent-unity status

You should see the project name, Unity version, port, and state.

3. Ask your AI agent to use it

Example prompt:

Use hera-agent-unity. Check the Unity console, enter Play Mode, reproduce the issue, and fix it.

The agent can then run commands like:

hera-agent-unity console --type error
hera-agent-unity editor play --wait
hera-agent-unity exec "return EditorSceneManager.GetActiveScene().name;"
hera-agent-unity test --mode PlayMode

Install

There are two parts:

1. the CLI program on your computer;
2. the Unity package inside your project.

CLI

npm (Windows, macOS, Linux)

npm install --global hera-agent-unity

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.ps1 | iex"

Open a new terminal after install, then check:

hera-agent-unity version

macOS / Linux

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

Go install

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

Manual

Download a binary from Releases, then run:

hera-agent-unity install

Unity Package

In Unity:

Window -> Package Manager -> Add package from git URL

Use this URL:

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

Or add this to Packages/manifest.json:

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

To pin a specific connector (UPM) version instead of tracking the latest, append an existing connector-<version> git tag:

"com.notnull92.hera-agent-unity": "https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector#connector-<version>"

Connector versions are separate from CLI v* releases.

The connector starts by itself when Unity opens.

Commands

Here are the commands most agents use first.

Full command list: docs/COMMANDS.md

Token Saving

Hera is built for agents, so small answers matter.

Big answers become input tokens. Input tokens cost money and fill context. So common Hera commands return small data by default.

Good default path:

hera-agent-unity list --compact
hera-agent-unity find_gameobjects --name Player --ids
hera-agent-unity list --tool manage_gameobject

Use bigger output only when needed:

hera-agent-unity list
hera-agent-unity find_gameobjects --fields all
hera-agent-unity console --lines 0 --stacktrace full

Unity UI From a Screenshot

Unity UI is hard for AI because anchors, pivots, and layout groups are easy to guess wrong.

Hera gives the AI a loop:

1. read the current UI;
2. build real Unity UI objects;
3. capture what Unity rendered;
4. compare and fix.

hera-agent-unity ui_doc export --path /Canvas/HUD
hera-agent-unity ui_doc sample --image hud_ref.png --region "0,0,1,0.2"
hera-agent-unity ui_doc apply --file hud.json --parent /Canvas --mode upsert
hera-agent-unity ui_doc capture --out hud_built.png

This is the main idea: do not guess the UI. Measure it. During ui_doc apply, Hera also reports the active official uGUI docs bucket (2022.3, 2023.2, 6000.0, 6000.3, or 6000.5), deterministic fixes, and remaining diagnostics so the agent can correct version-specific uGUI structure.

UI Systems

ui_system makes the output backend explicit. Set it in asset-config.json; each UI request stays within the selected backend. Hera never guesses from the scene or silently switches systems; a mismatched ui_doc.backend is rejected before any scene or asset mutation.

Choose uitk when the project uses runtime UI Toolkit:

hera-agent-unity asset-config ui-system uitk
hera-agent-unity ui_doc apply --file settings-uitk.json

The UITK document uses backend: "uitk", exact runtime element names, reflection-validated UXML attributes, and reflection-validated USS properties. Generated files live under Assets/HeraGenerated/UI.

See UI_DOC_IR.md for both backend contracts.

Input QA

Some agent environments cannot capture a reliable Unity screenshot state, so they refuse physical coordinate clicks. Hera's input command gives agents a separate Unity-level QA path.

hera-agent-unity input state
hera-agent-unity input inspect --path /Canvas/StartButton --details true
hera-agent-unity input click --path /Canvas/StartButton --settle_frames 2
hera-agent-unity input submit --path /Canvas/StartButton
hera-agent-unity input scroll --path /Canvas/ScrollRect --scroll_delta 0,-3
hera-agent-unity input drag --path /Canvas/Slider/Handle --to_normalized 0.8,0.5

input uses Unity's uGUI EventSystem.RaycastAll and ExecuteEvents pointer handlers. It can prove that the Unity UI event path works, including blockers, handlers, interactability, submit, scroll, and drag behavior.

Input work and diagnostics are bounded before dispatch: hold_ms ≤ 5000, settle_frames ≤ 120, steps ≤ 120, click_count ≤ 3, and max_results ≤ 100 (default 50). Invalid values return INPUT_INVALID_PARAM.

It is not a physical OS/window click. Report evidence separately:

Detailed command docs: docs/COMMANDS.md

Game Feel Mode (Beta)

AI can make a game that works. Game Feel Mode (Beta) helps it make a game that feels right.

When this mode is on, agents working through Hera get game-feel guidance for gameplay itself — screen shake, hit stop, knockback, control feel (coyote time, input buffering), camera work, sound design, reward presentation — with concrete parameters (px, seconds, %, Hz) from the Game Feel & Juice Bible and the Ethical Engagement Game Feel Framework.

The ethics are built in, not bolted on. Every recipe carries its constraints — screen-shake intensity options, flash-reduction for photosensitivity, honest reward presentation, transparent probabilities — so what the agent builds passes the ethics checklist by construction (Honest Juice: presentation intensity must match real achievement).

Three surfaces work together:

• hera-agent-unity game_feel <topic> — the bundled knowledge base (54 topics, ethics listed first), always available
• doctor --agent-rules — injects the core principles + workflow when the mode is on
• Tool hints — adding a Camera / ParticleSystem / AudioSource / Rigidbody / Light / Animator via manage_components points the agent at the matching topics

Guidance only — Hera never attaches runtime components for you.

Turn it on in Unity:

HeraAgent -> Hera Settings -> Game Feel Mode (Beta)

Or from the CLI: hera-agent-unity asset-config gamefeel on

Game Feel UI Mode (Beta)

AI can make a button that works. Game Feel UI Mode (Beta) helps it make a button that feels like a game.

When this mode is on, Hera adds an agent_hint to UI creation results. The hint gives concrete game-feel recipes: hover scale, press squash, release bounce, popup overshoot with symmetric choice buttons, rarity-laddered reward presentation, count-up numbers with critical specs, dual-response health bars, charge/cooldown patterns, ECN-DMN density guidance, haptics, and accessibility baselines. Each hint ends with a pointer into the game_feel knowledge base's ui category — per-element spec tables, cognitive-load theory, choice-symmetry ethics, and 2026 trends — for depth on demand.

It is guidance, not runtime bloat. Hera does not attach heavy gameplay components for you. The agent receives the recipe, then applies the animation or feedback through normal Unity edits.

The uGUI fixer is separate from the game-feel recipe: ui_doc apply always reports manual-backed fixes / diagnostics, while Game Feel UI Mode (Beta) only adds optional game-feel guidance in agent_hint.

Turn it on in Unity:

HeraAgent -> Hera Settings -> Game Feel UI Mode (Beta)

Or from the CLI: hera-agent-unity asset-config gamefeel-ui on

If DOTween is enabled in the same Hera Settings panel, the hint suggests DOTween-style tweens. If not, it falls back to coroutine or lerp-style guidance.

Common recipes:

Detailed command docs: docs/COMMANDS.md

Unity De-slop Mode (Beta)

Game Feel Mode covers how a screen moves. De-slop Mode covers how it sits still — the statistical tells that make generated UI look generated: reflexive decoration, undisciplined containers, spacing picked by eye, decorative italics, rainbow palettes.

The bundled ui_slop taxonomy groups these into five areas, and fixes land in that order so an upstream fix dissolves the conflicts a downstream one would hit:

Every tell carries a uGUI check and a UI Toolkit check, written against the USS vocabulary each Unity version actually ships, plus the mechanical fix and the functional cases that must not be treated as slop — nested surfaces are usually legitimate in game UI, so repeated interactive cells like inventory slots are never flattened.

hera-agent-unity ui_slop                 # taxonomy index by area
hera-agent-unity ui_slop box-in-box      # one tell: check, exception, fix

The tool is always available. Turning the mode on additionally makes doctor --agent-rules inject the de-slop discipline and manage_components add point at the relevant tell:

HeraAgent -> Hera Settings -> Unity De-slop Mode (Beta)

Or from the CLI: hera-agent-unity asset-config uislop on

Ultra Hera

Hera's signature verification mode for AI-assisted Unity work.

_{Ultra Hera helps an AI agent check its Unity work before it says "done".}

Ultra Hera is Hera's safety belt for AI Unity work.

When an AI changes code, a scene, or the Inspector, it can be wrong in small ways: Unity may not compile, the Console may have errors, a GameObject may not have the component you expected, or Play Mode may fail after the edit.

Ultra Hera gives the agent a simple rule:

Do the work. Check the work. Only then report the result.

It does not replace the AI. It tells the AI how carefully to verify Unity work after using Hera.

Find it here:

HeraAgent -> Hera Settings -> Ultra Hera

Modes:

Think of the modes like this:

Use Light for everyday coding and Inspector edits. Use Ultra when the user says things like "verify exactly", "play it and confirm", "match the UI", or "check the Inspector too".

What Ultra Hera makes agents do better:

• Check Unity instead of guessing.
• Read only the state they need.
• Compile after edits.
• Read real Console errors.
• Re-check the changed GameObject, component, asset, or UI.
• Use Play Mode, tests, screenshots, or ui_doc capture when the task needs stronger proof.
• Report short evidence instead of a vague "it should work".

Representative Light commands:

hera-agent-unity status
hera-agent-unity console --type error --lines 20
hera-agent-unity editor refresh --compile
hera-agent-unity find_gameobjects --ids
hera-agent-unity exec --depth 1 ...

Representative Ultra commands:

hera-agent-unity test --mode EditMode
hera-agent-unity test --mode PlayMode
hera-agent-unity editor play --wait
hera-agent-unity screenshot --view game
hera-agent-unity ui_doc capture --out ...

The goal is simple: the agent should not close the task while Unity is still broken.

Unity Versions

Add Project Rules For Agents

Put Hera rules in your Unity project so agents know how to use it before they start guessing.

Codex users can add the publisher-owned marketplace directly:

codex plugin marketplace add NotNull92/hera-agent-unity --ref main

Then open Codex, run /plugins, choose Hera Agent Unity, and enable Hera Unity. The same plugin is also mirrored by the HOL awesome-codex-plugins and awesome-ai-plugins catalogs.

For the standalone Agent Skill without the plugin marketplace:

npx skills add NotNull92/hera-agent-unity --skill hera-agent-unity --agent codex

Use either installation path; both teach the same CLI-first Unity workflow.

This repository includes ready-to-use rule files for the main coding agents:

Fast setup for the common shared file:

hera-agent-unity doctor --agent-rules >> AGENTS.md

Cursor setup:

hera-agent-unity doctor --agent-rules --format cursor > .cursor/rules/hera-agent-unity.mdc

Copilot, AntiGravity, and Continue templates are in examples/rules. This repo also contains live examples at .github/copilot-instructions.md, .github/instructions/hera-agent-unity.instructions.md, GEMINI.md, and .agents/skills/hera-agent-unity/SKILL.md.

The most important rules are:

• use list --compact to find available tools;
• use find_gameobjects --ids when the next command only needs object IDs;
• return null from side-effecting exec calls;
• do not return big Unity objects directly;
• read console --type error instead of guessing errors.

How It Works

Terminal / AI agent
        |
        | hera-agent-unity command
        v
Go CLI
        |
        | localhost HTTP
        v
Unity Editor package
        |
        | Unity main thread
        v
Scene, Console, Play Mode, Assets, UI

The Unity package starts a small local HTTP server. The CLI sends commands to it. The command runs inside the Editor.

Architecture details: docs/ARCHITECTURE.md

FAQ

Is this MCP?

The production default is a normal CLI, so any agent that can run shell commands can use Hera. CLI v0.1.0+ also includes an experimental, default-off, stdio-only MCP adapter. It reuses the CLI and localhost Connector execution core and is not the default. See the MCP adapter guide.

Does it need Python?

No.

Which Unity Editor does it talk to?

Each CLI invocation or MCP process targets one Unity Editor. If several Editor heartbeats are present, prefer --project with the full project path. Ports are temporary endpoints chosen from 8090–8099; they may change after an Editor restart or domain reload. Exact normalized project paths win, a partial project match must be unique, and --project plus --port must identify the same Editor. Without a selector Hera prefers a project matching the current working directory, then the most recent live heartbeat. After a transport failure or request timeout Hera reads fresh heartbeat state before any safe retry, so it does not silently follow a port that another project has claimed.

What should I do when it cannot connect?

Run:

hera-agent-unity doctor --json

Also check that the Unity package is installed and Unity has finished compiling.

Where are the detailed docs?

• docs/COMMANDS.md
• docs/MCP.md
• docs/ARCHITECTURE.md
• docs/CSHARP_CONNECTOR.md
• docs/TROUBLESHOOTING.md

Projects Using Hera

Author

Victor — Unity/C# developer with 6+ years of live-service MMORPG production experience.

GitHub: @NotNull92

Discord: Join the Hera community

Support

Hera is free and licensed under Apache-2.0. If it saves you time, you can support development:

License

Apache License 2.0. See LICENSE and NOTICE.