Control and verify a live Unity Editor through a local, low-token MCP server.
io.github.NotNull92/hera-agent-unity MCP Server
This local, low-token Model Context Protocol (MCP) server helps control and verify a live Unity Editor. It is designed for interacting with Unity tooling from a CLI/developer workflow, using Go-based implementation and relevant Unity concepts (editor tool and UPM package).
๐ ๏ธ Key Features
Control a live Unity Editor
Verify Unity Editor state
Operate via a local, low-token MCP server
๐ Use Cases
Automate Unity Editor actions during development
Validate changes made in the Unity Editor
Integrate Unity Editor control into an AI-agent or developer-tool flow
โก Developer Benefits
Aligns with developer-tool and CLI-tool workflows
Supports common Unity stack areas: Unity Editor tooling, Unity 2D/3D, and UPM packages
โ ๏ธ Limitations
Focused on Unity Editor control/verification; not described as general-purpose beyond that scope
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.
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:
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
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:
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.
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:
text
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
text
Use Hera. Read the Unity Console, find the actual error, fix the code,
compile again, and keep repeating until the error Console is clean.
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
text
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:
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_battle
validate_item_database
spawn_quest_fixture
bake_localization_table
check_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
Ultra Hera
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:
text
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.
Game Feel Mode (Beta)
Helps the agent think about how gameplay feels, not only whether it functions: control feel and input forgiveness, the Update / FixedUpdate / LateUpdate split, screen shake, hit stop, knockback, camera, sound, reward presentation, haptics, session pacing, and accessibility constraints.
bash
hera-agent-unity asset-config gamefeel on
hera-agent-unity game_feel hit_stop
hera-agent-unity game_feel unity_frame_loops
The knowledge is guidance. Hera does not secretly add heavy runtime systems to your game.
Game Feel UI Mode (Beta)
Adds practical UI feedback recipes such as hover scale, press squash, popup entrance, count-up text, health-bar response, cooldown feedback, and accessibility baselines.
bash
hera-agent-unity asset-config gamefeel-ui on
Unity De-slop Mode (Beta)
Helps agents catch common generated-looking UI habits: unnecessary decoration, weak spacing systems, box-in-box layouts, decorative italics, inconsistent colors, and other visual tells.
bash
hera-agent-unity asset-config uislop on
hera-agent-unity ui_slop box-in-box
The rules include exceptions so functional game UI such as inventory cells is not flattened just because it is repetitive.
Asset preferences and compiler defaults
Known assets such as Odin and DOTween can be enabled as preferences. Enabling
one does not install it; it tells generated agent rules and AI JSON to prefer
that API when the project actually contains it.
The compiler defaults are read by the next exec call, without restarting the
Editor. You can configure the same values from HeraAgent -> Hera Settings.
Command overview
You do not need to memorize these. They are here so you can understand the surface Hera gives an agent.
Command
Plain-language purpose
doctor --json
"Is Hera installed and can it reach Unity?"
status / ping
Check Editor state and liveness.
list --compact
Discover available built-in and project-specific tools cheaply.
call <tool>
Validate a strict live tool contract, then call it.
console
Read or clear the real Unity Console.
scene
Inspect, create, load, save, activate, list, or close Scenes; dump the GameObject tree.
find_gameobjects
Search the loaded Scene hierarchy.
manage_gameobject
Create and edit GameObjects.
manage_components
Read, add, remove, or modify Components.
manage_assets
Work with project assets under Assets/, bring in a file from outside the project, and trace dependencies. delete moves to the OS trash.
manage_prefab
Create, instantiate, and edit prefab assets, and apply, revert, or unpack an instance's overrides.
manage_animation
Author AnimationClips and AnimatorController state machines, and read them back.
manage_timeline
Create and inspect optional Timeline assets, tracks, and clips without taking a package dependency.
manage_settings
Read and change physics, time, quality, player, audio, graphics, legacy input, lighting, and legacy NavMesh settings with previews and approval.
hera-agent-unity doctor --agent-rules --compact >> AGENTS.md
The compact default guidance is intentionally small. Its reviewed baseline is 2,315 UTF-8 bytes and contains the important rules for bootstrap, targeting, approvals, safety, and verification. The full guide is available on demand.
This repository also ships templates for Cursor, Copilot, AntiGravity, Continue, and other agent environments under examples/rules.
Safety and reliability in plain language
Hera can make real changes to a Unity project, so "fast" is not enough. It also needs to know when to stop.
It identifies the project, not just a port number
Unity can change its local port after a domain reload or restart. Hera prefers the normalized full project path as the Editor identity and treats the port as a temporary endpoint.
If several Editors are open, use:
bash
hera-agent-unity --project /full/path/to/project status
Ambiguous targeting fails instead of guessing.
Risky operations can require approval
Approval-gated work is preflighted first. The returned token is tied to that exact request and is single-use. Changing the target or arguments invalidates the approval. In a shell or CI job you already trust, --yes (env: HERA_AGENT_APPROVE=1) answers the preflight in the same invocation instead of returning APPROVAL_REQUIRED โ the preflight and the operation ledger still run.
It does not blindly repeat an uncertain mutation
If a response disappears during a reload or timeout, Hera checks fresh Editor ownership/state before an eligible retry. A mutation is not resent merely because the network response was unclear.
Slow tests can be resumed instead of started again
A long Test Runner job can outlive a normal request window. Hera stores durable run state so an agent can resume waiting for the same run instead of accidentally starting another test execution.
Unity versions
Unity version
Status
Representative verification
6000.6+
Supported
6000.6.6f1 release gate
2022.3
Developer Mode (opt-in, unsupported)
Representative 2022.3.62f2; separate verification
Other Editor lines
Not supported
Explicit compile-time error
Version-specific behavior is checked against live Editors rather than assumed from one Unity version.
Representative Editors follow the Unity series used by the author's game: currently 6000.6, represented by 6000.6.6f1.
Within two weeks of a new series' stable release, add a representative and run the Connector release gate; alpha and beta releases are not tracked. Until the gate passes, mark that series Checking.
Game crunch takes priority: defer these checks during crunch and leave the series Checking.
Raise the minimum only when the game moves to a new series or an actual case shows the old series blocking a necessary fix. Announce it one minor release ahead in this README and CHANGELOG, raise it in a Connector minor release, and list the last Connector tag supporting the old series here so users can pin #connector-X.Y.Z.
Any shell-capable coding agent can drive it, and every command answers with the
same compact JSON envelope over the same catalog, approval flow, and operation
ledger.
CLI v0.1.0-v0.2.x also carried an experimental, default-off, stdio-only MCP
adapter. It was removed in v0.3.0. The adapter sat in front of the same
execution core, so it never unlocked a Unity capability the CLI did not already
have, and keeping a second protocol surface meant a second discovery, approval,
and result path to maintain. Use the CLI directly: list to discover, call for
typed execution, exec when no dedicated command exists.
What Hera is not
Not AI: the coding agent makes decisions; Hera provides access to the Editor.
Not a game runtime tool: the Connector is Editor-only (HeraAgent.asmdef includes only Editor).
No second protocol: the CLI is the only agent surface; there is no MCP adapter or separate persistent or relay server alongside it.
No real-time channel: every call is one request and one response; there are no progress streams or push notifications.
No multi-Editor control in one command: each command targets one Editor; use --project to select it when several are open.
Not a sandbox:exec defaults to Full Access; Restricted is one layer of defense.
New features require a reproduced failure. See Contributing.
Current release
CLI / GitHub Release: v0.3.25 with five native binaries
npm: 0.3.25 (latest)
Unity Connector: 0.3.0 (pin with #connector-0.3.0)
License: Apache-2.0
The npm publish is chained to the GitHub Release, so npm install -g hera-agent-unity and the GitHub binaries stay in step.
The two version numbers are separate on purpose. The CLI and the Unity package can evolve independently while keeping their compatibility contract explicit.
Upgrading from v0.2.x: v0.3.8 was the first published 0.3 release, so it also carries the breaking v0.3.0 changes. The experimental MCP adapter is gone: there is no mcp command and no HERA_MCP_* environment variable. A failed request now declares how it can be retried (retryable, state, retry_after_ms), and the heartbeat advertises the catalog schema hash so a matching catalog is reused without another round-trip. Connector 0.2.x requires Unity 6.6 (6000.6), and its instance_id values are 64-bit. The live catalog exposes 34 tools / 133 actions.
What's new since v0.2.17:
Version
Change
v0.3.25 / 0.3.0
Opt-in Developer Mode for Unity 2022.3: the Connector compiles on 2022.3.62f2 and refuses requests with DEVELOPER_MODE_REQUIRED until you run asset-config developer-mode on or enable it in Hera Settings. Unity 6.6+ behavior is unchanged and remains the supported line. Update the Connector to 0.3.0 as well.
v0.3.24 / 0.2.14
scene save returns SCENE_UNSAVED for a dirty untitled scene instead of opening a Save dialog. Input System keyboard/mouse responses report the player-side state, scroll and delta reach the player for one frame, settle_frames=0 sequence/replay steps apply in the same update, and a missing player update fails within 2000 ms with a focus/Run In Background hint. Help and agent rules updated. Update the Connector to 0.2.14 as well.
v0.3.23 / 0.2.13
Legacy NavMesh changes mark the active scene dirty without saving unrelated assets. Save the scene to keep them; writes during Play Mode are rejected. No CLI behavior change. Update the Connector to 0.2.13.
v0.3.22 / 0.2.12
Asset edits save only changed asset files; manage_assets delete moves to the OS trash. Query one action with list --tool --action. Shorter tool descriptions and a budget for the complete compact Light rules output. Update the Connector to 0.2.12 as well.
v0.3.21 / 0.2.11
Windows PATH cleanup preserves its original form; uninstall removes the actual state folder; update verifies SHA-256. Tool JSON stays compact (--compact-json is for compatibility), with nine more help topics. Hera's own tool failures no longer add console errors, repeated hints are shorter, and Restricted exec blocks screenshot and profiler file writes. Update the Connector to 0.2.11 as well.
v0.3.20
The guide page adds a decisions chapter (VIII) that collects the settled policies, and its explanations are rewritten in plain language. No CLI behavior or Connector change.
v0.3.19
Public-product policies: CONTRIBUTING.md (what starts work, response targets, compatibility), a one-week security response target, "What Hera is not", and how Hera follows new Unity releases. No CLI behavior or Connector change.
v0.3.18
The guide page drops the two fixed risks (port-keyed result lookups, blocking-modal detection) and their artwork. No CLI behavior or Connector change.
v0.3.17
task status <op_id> shows whether a command that ended in OPERATION_OUTCOME_UNKNOWN actually ran. It reads the local operation record, so it answers immediately even while the Editor is blocked; the timeout message now names this command. No Connector change.
v0.3.16
The agent guide (doctor --agent-rules) adds "one Editor runs one command at a time": a command abandoned by a CLI timeout still runs later, so give each agent its own Editor and re-read the target before resending. No CLI behavior or Connector change.
v0.3.15
On Windows, a timeout explains custom and nested Editor modals (with the window title), and progress windows that close by themselves are no longer reported as dialogs a person must close. A heartbeat from another live process no longer counts as an Editor restart. No Connector change.
v0.3.14 / 0.2.10
Async waits and test --resume keep finding the original result after a domain reload moves the Editor port; the test-run lock and test cancel see runs from any port. Asset import workers no longer start the Connector, so they cannot overwrite the project heartbeat or take ports. Update the Connector to 0.2.10 as well.
v0.3.13
The guide page becomes "Hera Unity Status": a request-flow map, skill trees that explain each tool, a risk bestiary and embedded artwork. No CLI or Connector behavior change.
v0.3.12
Adds the standalone Hera guide page (docs/guide/index.html); no CLI or Connector behavior change.
v0.3.11
Decimal/exponent arguments use Unity's argument hash; package jobs wait for a real result port.
v0.3.10 / 0.2.9
Game Feel UI recipes attach once per element type per Editor session; manage_components drops redundant type/enabled fields; compact agent rules shrink to 2,315 B.
v0.3.9
During a domain reload the CLI keeps retrying the last valid port instead of dialing port 0.
v0.3.8 / 0.2.8
Leaner default payloads: exec returns Unity Objects as {name, type, instanceID} unless --depth 3+ is explicit (a Transform drops from 7,178 B to 70 B); scene hierarchy omits default active/children; error envelopes drop duplicate hints and timings.
v0.3.7
Windows Editor launch also finds versions in the Unity Hub secondary install folder.
v0.3.6
list --profiles and list --profile <name> show task-scoped tool sets from the cached catalog.
v0.3.5
A request stuck behind a native Editor dialog reports blocked_by_dialog with the dialog title (Windows).
0.2.5โ0.2.7
Test shards follow the same selector rules as unsharded runs; exec writes a metadata-only journal.
v0.3.4 / 0.2.4
test --format junit|nunit artifacts and deterministic --shard-index/--shard-count splitting.
v0.3.1โv0.3.3
Catalog baseline measures the CLI; 64-bit id fixes; atomic batch preflight for Undo-covered edits.
For release-by-release engineering detail, read CHANGELOG.md instead of treating the main README as a migration log.
How does Hera work internally?
text
Terminal / AI agent
|
| hera-agent-unity command
v
Go CLI
|
| localhost HTTP
v
Unity Editor package
|
| serialized Unity main-thread work
v
Scene, Console, Play Mode, Assets, Tests, UI
The Unity package opens a local HTTP listener. The CLI selects the intended Editor from local heartbeat state and sends the command. Unity work is marshaled to the Editor main thread.
Domain reloads and long-running operations use filesystem-backed state so compilation, tests, and recovery can survive the HTTP listener being recreated.
Prefer dedicated commands over arbitrary exec when one exists.
Use small projections such as find_gameobjects --ids when IDs are enough.
Side-effecting exec snippets should normally return null or nothing rather than a large status object.
Do not return a full UnityEngine.Object unless you truly need its reflected graph.
Use --strict or throw an exception when a logged error must fail the CLI operation.
Use --security-mode restricted when a snippet only needs platform APIs and should be denied file, network, process, reflection, native, threading, UnityEditor, and project-assembly access. Full Access remains the default.
Use exec --check when you want to compile-check a snippet without executing it.
Long asynchronous workflows are better represented as tracked [HeraTool] actions or durable task/test operations than as detached work inside a one-shot exec.
No. Hera gives the AI better access to your real Unity state and better ways to verify the result. The coding model still makes the design and implementation decisions.
Does it need Python?
No. The normal install is one native CLI plus one Unity package.
Is a host protocol required?
No. The CLI is the only surface. It speaks localhost HTTP to the Unity package and nothing else.
Can it control more than one open Unity Editor?
Each command targets one Editor. If several are open, use the full --project path for the clearest selection. Hera tracks the selected project identity even if the local port changes.
Can it physically click the Unity window?
The input command sends Unity EventSystem events for uGUI QA and can synthesize optional Input System keyboard/mouse state in Play Mode. Both prove Unity-level behavior, not a physical operating-system click. Physical click evidence must be reported separately.
What should I do if it cannot connect?
bash
hera-agent-unity doctor --json
Also check that the Unity package is installed and the Editor has finished compiling.