[](https://github.com/NotNull92/hera-agent-unity/releases)
[](https://github.com/NotNull92/hera-agent-unity/stargazers)
[](LICENSE)
[](https://go.dev)
[](https://unity.com)
[]()
# hera-agent-unity
**Give your AI coding agent hands, eyes, and a checklist inside Unity.**
Codex, Claude, Cursor, Copilot, AntiGravity, and other shell-capable agents can inspect your live Unity Editor, change it, run it, test it, see the result, and keep fixing until the evidence says it is done.
[Start in 3 steps](#how-do-i-use-it) · [What can it do?](#what-can-it-actually-do) · [Why Hera?](#why-use-hera) · [How good is it?](#how-good-is-it) · [Examples](#what-can-i-do-with-it) · [Commands](#command-overview)
[English](README.md) · [한국어](README.ko.md)
---
## Hera in one minute
An AI can write Unity C# without Hera, but it cannot reliably know what your **live Editor** looks like after the code is written.
Normally the loop looks like this:
```text
You ask the AI
↓
AI writes code
↓
You open Unity and wait for compile
↓
You copy the error back to the AI
↓
AI fixes it
↓
You press Play and explain what happened
↓
repeat...
```
Hera closes that loop:
```text
You ask the AI
↓
AI uses Hera
↓
Unity compiles, runs, tests, clicks UI, captures the result
↓
Hera gives the real result back to the AI
↓
AI fixes what failed and checks again
↓
verified result
```
A simple way to think about it:
> **The AI is the brain. Hera gives that brain hands to operate Unity, eyes to inspect the result, and a checklist so it does not stop while the project is still broken.**
Hera does not replace Unity and it does not replace the coding agent. It connects the two so the agent can work with facts from your actual project instead of guessing from source code alone.
---
## What problem does it solve?
Unity development has a feedback loop that lives outside the source files.
A change can look correct in code and still fail because:
- Unity did not compile it;
- the wrong Scene is open;
- a GameObject or Component is missing;
- the Inspector has a different serialized value;
- a Unity API changed in your Editor version;
- the Console contains an exception;
- Play Mode behaves differently from Edit Mode;
- a button is visually present but cannot receive input;
- a UI layout is technically valid but looks wrong;
- the AI says "done" before it has actually checked any of those things.
Hera lets the agent ask the real Editor instead.
```bash
hera-agent-unity status
hera-agent-unity console --type error
hera-agent-unity scene info
hera-agent-unity editor play --wait
hera-agent-unity test --mode PlayMode
```
If the selected Editor is not running, Hera can bootstrap the exact project
before Connector discovery:
```bash
hera-agent-unity --project C:/Projects/Game editor launch
hera-agent-unity --project C:/Projects/Game editor restart
```
The project version comes from `ProjectSettings/ProjectVersion.txt`; the
matching Unity Hub install comes from `UNITY_HUB_EDITOR` or the platform default
(`%ProgramFiles%\Unity\Hub\Editor` on Windows). Pass `--hub-root` for a custom
Hub location. Startup uses normal Package Manager behavior, not `-noUpm`, and
returns when the new process publishes that exact project's heartbeat. On
Windows, Hera also restores the standard common-profile environment for the
Unity child when an agent shell omitted it, so UPM path resolution still starts
with the same baseline as a normal desktop launch.
The important part is not the command names. The important part is that the agent can **observe → change → run → verify → repair** without making you act as the courier between the AI and Unity.
---
## What can it actually do?
You can use Hera for tiny one-line checks or for a full AI-assisted Unity workflow.
| What you want the AI to do | What Hera gives it |
|:---|:---|
| Check whether Unity is healthy | Live Editor status, version, project, compile state, Console errors |
| Start or restart the right Editor | Launch or restart the exact project from its recorded Unity version and wait for that project's heartbeat |
| Understand the current Scene | Scene info, GameObject search, Component and Inspector reads |
| Change the Scene | Create/save Scenes; create, duplicate, rename, parent, transform, tag, layer, or delete GameObjects |
| Edit Components | Add, remove, inspect, and change serialized Component values |
| Work with project assets | Find, create, copy, move, or delete assets under `Assets/` |
| Run project-specific C# | Execute C# inside the loaded Editor with access to Unity APIs and project assemblies |
| Make animations | Author AnimationClips, AnimatorController state machines, and Timeline tracks/clips |
| Test a feature | Run EditMode and PlayMode tests and keep the result across domain reloads |
| Play the game | Enter Play Mode, wait for the real state change, inspect, then stop |
| See what Unity rendered | Capture Scene/Game views or isolated objects, plus bounded uGUI identity/coordinate and Camera.main 3D physics evidence |
| Test Unity input | Inspect uGUI raycasts, or synthesize Input System keyboard/mouse sequences, record them, and replay them in Play Mode |
| Build UI | Author uGUI layouts and verify the generated result |
| Recreate a reference UI | Measure a reference, build the real Unity UI, capture it, compare, and iterate |
| Improve game feel | Give the agent recipes for shake, hit stop, feedback, camera, sound, rewards, and accessibility |
| Clean up generated-looking UI | Detect common spacing, hierarchy, typography, color, and decoration problems |
| Create your own studio commands | Add project-specific `[HeraTool]` actions that appear automatically |
| Work with several open Editors | Target the intended project and keep that project identity through port changes |
| Require approval for risky work | Preflight destructive operations and continue only with the matching approval token |
In short, Hera is not just a "press Play" remote. It is a bridge for the **whole edit-and-check loop** around a running Unity project.
---
## Why use Hera?
### 1. The AI can check its own work
Without Editor access, the agent often ends with:
> "This should work."
With Hera, it can finish with evidence such as:
```text
compile: passed
console errors: 0
EditMode tests: 18/18
PlayMode tests: 6/6
button click: verified through EventSystem
final Game View: captured
```
That difference is the main reason Hera exists.
### 2. You stop being the copy-and-paste bridge
You no longer need to repeatedly:
1. copy code from the AI;
2. switch to Unity;
3. wait for compile;
4. copy errors back;
5. explain the Scene hierarchy;
6. press Play;
7. describe what happened.
The AI can perform most of that loop itself.
### 3. It works with the tools you already use
The normal production path is a CLI. Any agent that can run shell commands can use it.
- Codex
- Claude Code
- Cursor
- GitHub Copilot
- AntiGravity
- scripts and CI jobs
- your own automation
No Python server is required, and no host protocol has to be configured.
### 4. It is designed for AI context, not just humans
A giant tool response becomes more input for the model to read. Hera therefore gives common commands compact views such as IDs-only GameObject searches and on-demand tool schemas.
The goal is simple: **send the agent the smallest amount of Unity state that is enough to make the next decision.**
### 5. It knows that "request sent" is not the same as "work finished"
Unity recompiles scripts, reloads domains, changes ports, enters Play Mode, runs tests, and sometimes drops a connection while doing it.
Hera tracks these workflows instead of treating a successful HTTP send as proof that Unity is finished.
### 6. It can grow with your project
Start with the built-in commands. Later you can add a `[HeraTool]` for the workflow your own project repeats every day: build a dungeon room, validate a quest graph, bake a table, spawn a test battle, or check your studio-specific asset rules.
---
## How good is it?
Hera avoids vague "AI magic" claims. The repository keeps concrete measurements and compatibility evidence instead.
### Small responses for common agent reads
Measured low-token baselines for `list --compact` are **about 93 estimated tokens** across the tested Unity versions. `find_gameobjects --ids` measured **49 to 55 estimated tokens** in the retained cross-version fixtures.
| Unity Editor | `list --compact` | `find_gameobjects --ids` |
| `list --tool 