Enables AI coding agents to inspect, control, and verify live Unity Editor sessions through a low-token command-line interface.
Also known as NotNull92/hera-agent-unity, hera-agent-unity
- Stars
- 30
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 0.2.17
- Last commit
- Oct 29, 2026
- License
- Apache-2.0
What is Hera Agent Unity MCP?
Hera Agent Unity enables AI coding agents to inspect, control, and verify live Unity Editor sessions through a low-token command-line interface. It exposes 5 tools, such as build_test_battle, validate_item_database, spawn_quest_fixture.
Summary generated from the project's README
About Hera Agent Unity MCP server
Hera Agent Unity provides a command-line interface that allows AI coding agents to interact directly with a live Unity Editor session. Instead of developers manually copying errors or describing scene hierarchies to an AI, this tool enables agents to observe, change, run, and verify their own work. It is designed for shell-capable agents like Claude Code, Cursor, and GitHub Copilot, acting as a bridge between the AI brain and the Unity engine.
Users can manage the entire development loop through specific commands such as status checks, console error inspection, and scene information retrieval. The server can bootstrap projects by launching the correct Unity version from the Unity Hub and waiting for a project heartbeat. It supports complex tasks like editing component values, managing assets, running PlayMode tests, and even capturing Game View renders to provide visual evidence of success. This setup ensures that an agent does not claim a task is finished until the editor confirms the code compiles and the features function as intended.
What you can do with it
- 1Scene and hierarchy manipulationA developer can task an AI with modifying the game world by creating or transforming GameObjects.
- 2Automated functional testingThe agent can execute PlayMode tests to verify that new code behaves correctly during gameplay.
- 3UI layout verificationAn AI can build user interfaces and then capture the rendered view to ensure the layout is correct.
Written from the project's README. Every use case is checked against a quote from it.
How to install Hera Agent Unity MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Hera Agent Unity MCP in Claude Code
$ claude mcp add hera-agent-unity -- npx -y hera-agent-unityInstall Hera Agent Unity MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hera-agent-unity": {
"command": "npx",
"args": [
"-y",
"hera-agent-unity"
]
}
}
}Install Hera Agent Unity MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hera-agent-unity": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"hera-agent-unity"
]
}
}
}Install Hera Agent Unity MCP in VS Code CLI
$ code --add-mcp '{"name":"hera-agent-unity","type":"stdio","command":"npx","args":["-y","hera-agent-unity"]}'Install Hera Agent Unity MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hera-agent-unity": {
"command": "npx",
"args": [
"-y",
"hera-agent-unity"
]
}
}
}Install Hera Agent Unity MCP in Codex
$ codex mcp add hera-agent-unity -- npx -y hera-agent-unityInstall Hera Agent Unity MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hera-agent-unity] command = "npx" args = ["-y", "hera-agent-unity"]
Install Hera Agent Unity MCP in Gemini CLI
$ gemini mcp add -s user hera-agent-unity npx -- -y hera-agent-unityInstall Hera Agent Unity MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hera-agent-unity": {
"command": "npx",
"args": [
"-y",
"hera-agent-unity"
]
}
}
}Hera Agent Unity MCP tools 5
Detected from the READMEbuild_test_battlevalidate_item_databasespawn_quest_fixturebake_localization_tablecheck_prefab_rules
| build_test_battle | — | |
| validate_item_database | — | |
| spawn_quest_fixture | — | |
| bake_localization_table | — | |
| check_prefab_rules | — |
Configuration
HERA_MCP_ENABLED
| Name | Description | |
|---|---|---|
| HERA_MCP_ENABLED | — |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubhera-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 · What can it do? · Why Hera? · How good is it? · Examples · Commands
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:
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:
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.
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:
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:
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:
- copy code from the AI;
- switch to Unity;
- wait for compile;
- copy errors back;
- explain the Scene hierarchy;
- press Play;
- 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 <name> --action <action> | Read only the selected action parameters, result and safety. |
|:---|---:|---:|
| 2022.3.62f2 | 93 T | 54 T |
| 2023.2.22f1 | 93 T | 54 T |
| 6000.3.5f2 | 93 T | 49 T |
| 6000.5.0f1 | 93 T | 55 T |
T is a simple ceil(UTF-8 bytes / 4) estimate for Hera's CLI payload only. It is not provider billing telemetry. Full methodology: token-reduction benchmark.
Developer Mode on Unity 2022.3
Connector 0.3.0 compiles on Unity 2022.3, but dispatched requests are refused by default with DEVELOPER_MODE_REQUIRED. Enable Developer Mode (Unity 2022.3) in Hera Settings or run hera-agent-unity asset-config developer-mode on; use off to disable it. asset-config developer-mode shows the value and asset-config --json includes developer_mode (read-only).
The setting applies to every Unity 2022.3 project on this machine. Unity 6.6+ ignores it. A missing file/key defaults to off; malformed or locked configuration reads keep the last good value until a successful refresh. Changes need no domain reload. Status and ping still work while locked; cached local-only catalog queries and validation can also succeed, but dispatched requests are refused.
This is an unsupported opt-in line. On 2022.3.62f2, scoped paths for TMP 3.0.7, Timeline 1.7.7, Input System 1.14.0 and AI Navigation 1.1.6 passed independent verification; the package-present Hera suite passed 51/51. Keyboard and mouse delivery matched the same probe on 6000.6.6f1 with Input System 1.20.0. See versions, paths and evidence. unity_docs uses the 6000.6 corpus: both its unity_version and docs_version describe documentation, so compare them with the Editor version in status. With test-framework older than 1.4.0, cancel cannot stop a run whose callback is active in this domain; it preserves its pending record until completion. Stale records without an active callback can still be released.
All other Editor lines (including 2023.x and 6000.0–6000.5) hit an explicit #error. This stops normal project compilation, and other compiler errors may appear alongside it. Remove the package or use one of the two allowed lines.
Compatibility is checked across Unity generations
Supported Unity versions are Unity 6.6+ (6000.6 minimum). The release compile gate installs the Connector's exact source as a normal UPM dependency in a disposable blank project of the representative Editor and requires a clean compile, a green release-gate suite, and zero console errors:
| Bucket | Representative Editor | Last full-gate result |
|---|---|---|
| 6000.6+ | 6000.6.6f1 | PASS |
Connector 0.3.0 at 925e020 passed the required 6000.6.6f1 gate independently: clean normal/testables imports, unchanged catalog, and 48 tests passed with 0 failed and 1 Timeline skip in the blank template. Gate evidence. The released 0.3.0, which also carries the 0.2.14 scene save and Input System fixes, passed again: on 6000.6.6f1, 0 errors, no new warnings, unchanged catalog, 49 passed / 0 failed / 1 Timeline skip; on 2022.3.62f2 with Developer Mode on, 52/52 with the same input delivery. Release evidence.
Unity 6.6+ remains the supported line. Connector 0.3.0 also compiles on Unity 2022.3 behind the opt-in Developer Mode gate below. Its uGUI dependency resolves to the Editor's built-in version; the compile-time allow-list rejects other Editor lines. The package minimum alone does not enforce this boundary for git installs.
CLI and Connector versions are intentionally separate.
v0.2.0 was exercised in a live Editor, not only compile-tested
The final release candidate was loaded as Connector 0.0.86 in Unity 6000.5.6f1 with Input System 1.20.0 and driven through real Play Mode before release. The retained smoke evidence recorded:
- 31 tools / 80 actions from the live catalog;
- keyboard down/up and mouse position synthesis in Play Mode;
- a bounded input sequence completing successfully;
- an input recording with 5 events / 588 bytes, then two successful replays of the same file;
- zero Hera-owned controls left held after replay;
- Connector
ReleaseGateTests: 18/18 PASS; - Unity Console errors after the run: 0;
- graceful Editor shutdown with 0 new scene-recovery backups, while the disposable fixture manifest and lock file were restored.
This complements the five-version compile matrix with an end-to-end Editor regression on the released capability set.
A real game-creation run reached a verified playable result
The retained Crystal Forge scenario asked an AI to author code and tests, build UI, compile, drive Unity EventSystem input, run tests, capture the rendered result, and leave the Editor clean.
Final result: PASS after repair. First attempt: FAIL.
The measured execution window was 15 minutes 52 seconds. The run is useful because the failures were kept instead of being edited out. It showed why a closed verification loop matters: hidden state was correct before the UI was actually visible, and the agent had to observe, repair, and verify again.
This is not a claim that Hera makes every task succeed on the first try, and it is not an "X% smarter AI" benchmark. It demonstrates something more practical: Hera can give an agent enough real Editor feedback to find and repair integration failures instead of stopping at the first plausible answer.
Full evidence: Crystal Forge real-world benchmark.
How do I use it?
There are only two pieces:
your computer your Unity project
────────────── ──────────────────
Hera CLI <----------> Hera Unity Connector
Step 1. Install the CLI
The simplest cross-platform option is npm:
npm install --global hera-agent-unity
Or use the native installer.
Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.ps1 | iex"
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.sh | bash
Check it:
hera-agent-unity version
Go install
go install github.com/NotNull92/hera-agent-unity@latest
Manual
Download a binary from GitHub Releases, then run:
hera-agent-unity install
Step 2. Add the Unity package
In Unity:
Window -> Package Manager -> Add package from git URL
Paste:
https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector
Or add it to Packages/manifest.json:
"com.notnull92.hera-agent-unity": "https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector"
The Connector starts automatically when the Editor opens.
To pin an existing Connector tag:
"com.notnull92.hera-agent-unity": "https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector#connector-<version>"
The current released Connector pin is:
https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector#connector-0.3.0
Step 3. Open Unity and check the connection
hera-agent-unity doctor --json
hera-agent-unity status
You should see the real project path, Unity version, Editor state, and connection information.
Now you can simply tell your agent:
Use hera-agent-unity for this Unity project.
Check the current Editor state first.
Make the requested change.
Compile it, read the real Console errors, verify the changed object or UI,
and do not say it is finished until Unity is in a clean state.
That is the normal Hera workflow.
What can I do with it?
Fix a compiler or runtime error
Use Hera. Read the Unity Console, find the actual error, fix the code,
compile again, and keep repeating until the error Console is clean.
Typical commands behind the scenes:
hera-agent-unity console --type error --lines 20
hera-agent-unity editor refresh --compile
hera-agent-unity console --type error --lines 20
Build a feature and prove it works
Implement the inventory filter.
Use Hera to compile it, run the relevant EditMode and PlayMode tests,
enter Play Mode if needed, and report the final evidence.
Reproduce a gameplay bug
Open the correct Scene, enter Play Mode, inspect the related objects,
reproduce the bug, fix it, then reproduce the same path again to prove the fix.
Build UI from a reference image
Hera can give the agent a measurement loop instead of an eyeballing loop:
reference image
↓ sample colors / measure layout
Unity UI
↓ capture
compare
↓ fix
capture again
Example commands:
hera-agent-unity manage_ui create --element panel --name HUD
hera-agent-unity manage_ui set_anchor --path /Canvas/HUD --preset stretch --snap true
hera-agent-unity manage_components set --path /Canvas/HUD --property m_Color --value '#1A1A2E'
hera-agent-unity screenshot --overlay --output_path hud_built.png
Use manage_ui, manage_components, and screenshot --overlay in small verified batches.
Verify buttons without guessing screen coordinates
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
This verifies Unity's EventSystem path. It is not a physical Windows/macOS mouse click, so Hera reports those two kinds of evidence separately.
Projects that already use the optional Input System package can also verify gameplay input without adding a Hera dependency:
hera-agent-unity input state --backend inputsystem
hera-agent-unity input keyboard --key space --mode press
hera-agent-unity input mouse --mode click --button left --position 640,360
hera-agent-unity call input --json '{"action":"sequence","steps":[{"action":"keyboard","key":"space","mode":"down"},{"action":"keyboard","key":"space","mode":"up"}]}'
hera-agent-unity call input --json '{"action":"record","mode":"start"}'
hera-agent-unity call input --json '{"action":"record","mode":"stop"}'
hera-agent-unity call input --json '{"action":"replay","path":"Library/HeraAgent/Recordings/input.json"}'
Keyboard, mouse, bounded sequence, recording capture, and replay require Play Mode. Recordings use the bounded hera.input-recording/1 JSON format under the project or system temp directory; replay validates the complete file before mutation and reuses sequence-owned cleanup. Hera resolves the package at runtime, never creates devices, and releases any held controls when Play Mode exits.
Input System response values describe the player-side state at the end of the input update that applied the request's last change, preserved through settle_frames. press/click report the release update (pressed_after=false); down reports true. Each change waits up to 2000 ms for its configured update. Manual mode requires your project's own InputSystem.Update() pump; Hera does not pump it or change input policy. A missing update returns INPUTSYSTEM_INVOCATION_FAILED, while pause/exit use their existing Play Mode errors. When Unity is in the background with Run In Background off, player updates stop and INPUTSYSTEM_INVOCATION_FAILED results; focus Unity or enable Run In Background. See the Unity verification evidence and scope.
Sequence and replay group consecutive instantaneous steps connected by settle_frames=0 into one configured player input update, applying them in order and capturing once. press/click are group boundaries and keep their hold/release behavior. Nonzero settle counts still mean Editor updates, including the gaps loaded from recordings; they do not promise player-frame timing.
Automate repetitive Scene work
scene save rejects a dirty untitled Scene with SCENE_UNSAVED instead of opening a Save dialog. Save it once from the Editor, or create it with scene create <Assets/...unity> before editing. A clean Scene remains a no-op. Explicit generic menu/exec calls can still open modal dialogs.
You can ask an agent to:
- create a test arena;
- place prefabs under a new root;
- add and configure Components;
- create ScriptableObject assets;
- wire Animator states;
- save the Scene;
- run validation afterwards.
Create studio-specific tools
If your project has a repeated workflow, expose it as a custom [HeraTool]. The tool appears in Hera's live catalog automatically.
Examples:
build_test_battlevalidate_item_databasespawn_quest_fixturebake_localization_tablecheck_prefab_rules
Hera can therefore start as a generic Unity bridge and gradually become a CLI for your own game production pipeline.
Ultra Hera: make "done" mean checked
Do the work. Check the work. Only then report the result.
Ultra Hera is a verification rule for AI-assisted Unity work. It does not write the feature by itself. It tells the agent how carefully to check the work it just did through Hera.
Find it in:
HeraAgent -> Hera Settings -> Ultra Hera
| Mode | Easy meaning |
|---|---|
Off |
No extra verification rule. |
Light |
Default. Compile/check state, read errors, and re-read the changed target before finishing. |
Ultra |
For important work. Add stronger evidence such as tests, Play Mode, Inspector reads, and screenshots. |
Think of Light as a seatbelt check and Ultra as a pre-flight inspection.
Use Ultra when the request sounds like:
- "verify it exactly";
- "play it and confirm";
- "match this UI";
- "check the Inspector too";
- "do not finish until all tests pass".
The goal is simple: the agent should not close the task while Unity is still broken.
More than Editor control
Hera includes optional guidance and authoring systems that help the agent do more than change raw objects.
Hera Agent Unity MCP questions
How do I add Hera Agent Unity MCP to Claude Code?
Run claude mcp add hera-agent-unity -- npx -y hera-agent-unity in your terminal. Add --scope user to make it available in every project.
How do I add Hera Agent Unity MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Hera Agent Unity MCP provide?
It exposes 5 tools, including build_test_battle, validate_item_database, spawn_quest_fixture, bake_localization_table, check_prefab_rules.
What can Hera do within Unity?
Hera allows agents to check editor health, manage scenes, edit components, work with assets, run C# code, create animations, and perform PlayMode testing.
Does Hera replace the Unity Editor?
No, Hera acts as a bridge that connects an AI coding agent to your existing Unity Editor so the agent can work with real project facts.
How does Hera handle Unity project startup?
If the Editor is not running, Hera can bootstrap the specific project using its recorded Unity version and wait for the project's heartbeat.
Which AI agents are compatible with Hera?
Any shell-capable agent like Claude Code, Cursor, GitHub Copilot, or Codex can use Hera via its CLI.