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, no Python server.}

What it is · Why it helps · Quick Start · Install · Commands · Token Saving · Input QA · Game Feel Mode (Beta) · Game Feel UI Mode (Beta) · Ultra Hera · Unity Versions · Agent Rules · Projects · 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. No generated MCP config. No special agent plugin. If an agent can run a shell command, it can use Hera.

Release Highlights

Latest release: v0.0.39 (published July 7, 2026). This release adds ScriptableObject asset authoring and a connector-wide reliability and efficiency pass. The matching Unity package version is Connector 0.0.58.

Current verified 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

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"

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.

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.

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

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.

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?

No. It is a normal CLI. That is why it works with Codex, Claude Code, Cursor, and any agent that can run shell commands.

Does it need Python?

No.

Which Unity Editor does it talk to?

It is built around a single Unity editor per machine. If more than one instance is discovered — for example a leftover heartbeat from a previous session — use --project or --port to pick one.

hera-agent-unity --project MyGame status
hera-agent-unity --port 8091 status

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/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 MIT-licensed. If it saves you time, you can support development:

License

MIT. See LICENSE.