Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
HERA_MCP_ENABLED=<value> claude mcp add io.github.notnull92-hera-agent-unity -- npx -y hera-agent-unity@0.2.17In einem Terminal ausführen.
{ "mcpServers": { "io.github.notnull92-hera-agent-unity": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "HERA_MCP_ENABLED": "<value>" } } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenGive 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:
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.
Unity development has a feedback loop that lives outside the source files.
A change can look correct in code and still fail because:
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.
You can use Hera for tiny one-line checks or for a full AI-assisted Unity workflow.
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.
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.
You no longer need to repeatedly:
The AI can perform most of that loop itself.
The normal production path is a CLI. Any agent that can run shell commands can use it.
No Python server is required, and no host protocol has to be configured.
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.
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.
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.
Hera avoids vague "AI magic" claims. The repository keeps concrete measurements and compatibility evidence instead.
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.
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.
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:
The floor states what is actually verified: a single representative Editor, with no compatibility claim for any other Unity line. AgentConnector/package.json carries the 6000.6 floor, so Package Manager refuses the Connector on an older Editor instead of failing later at compile time.
CLI and Connector versions are intentionally separate.
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:
ReleaseGateTests: 18/18 PASS;This complements the five-version compile matrix with an end-to-end Editor regression on the released capability set.
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.
There are only two pieces:
your computer your Unity project
────────────── ──────────────────
Hera CLI <----------> Hera Unity Connector
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
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.2.10
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.
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
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.
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.
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.
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.
You can ask an agent to:
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_rulesHera can therefore start as a generic Unity bridge and gradually become a CLI for your own game production pipeline.
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
Think of Light as a seatbelt check and Ultra as a pre-flight inspection.
Use Ultra when the request sounds like:
The goal is simple: the agent should not close the task while Unity is still broken.
Hera includes optional guidance and authoring systems that help the agent do more than change raw objects.
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.
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.
Adds practical UI feedback recipes such as hover scale, press squash, popup entrance, count-up text, health-bar response, cooldown feedback, and accessibility baselines.
hera-agent-unity asset-config gamefeel-ui on
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.
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.
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.
hera-agent-unity asset-config enable odin_inspector
hera-agent-unity asset-config --json
hera-agent-unity asset-config set-csc <path-to-csc>
hera-agent-unity asset-config set-dotnet <path-to-dotnet>
The compiler defaults are read by the next exec call, without restarting the
Editor. You can configure the same values from HeraAgent -> Hera Settings.
You do not need to memorize these. They are here so you can understand the surface Hera gives an agent.
Full reference: docs/COMMANDS.md.
You can put Hera's operating rules in the project so the agent knows to inspect Unity before guessing.
codex plugin marketplace add NotNull92/hera-agent-unity --ref main
Then open /plugins, choose Hera Agent Unity, and enable Hera Unity.
npx skills add NotNull92/hera-agent-unity --skill hera-agent-unity --agent codex
AGENTS.mdhera-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.
Hera can make real changes to a Unity project, so "fast" is not enough. It also needs to know when to stop.
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:
hera-agent-unity --project /full/path/to/project status
Ambiguous targeting fails instead of guessing.
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.
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.
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.
Version-specific behavior is checked against live Editors rather than assumed from one Unity version.
Hera is a plain command-line binary.
AI / terminal -> Hera CLI -> localhost Connector -> Unity Editor
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.
latest)#connector-0.2.10)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:
For release-by-release engineering detail, read CHANGELOG.md instead of treating the main README as a migration log.
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.
Architecture details: docs/ARCHITECTURE.md.
exec when one exists.find_gameobjects --ids when IDs are enough.exec snippets should normally return null or nothing rather than a large status object.UnityEngine.Object unless you truly need its reflected graph.--strict or throw an exception when a logged error must fail the CLI operation.--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.exec --check when you want to compile-check a snippet without executing it.[HeraTool] actions or durable task/test operations than as detached work inside a one-shot exec.The complete agent operating guide is AGENTS.md.
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.
No. The normal install is one native CLI plus one Unity package.
No. The CLI is the only surface. It speaks localhost HTTP to the Unity package and nothing else.
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.
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.
hera-agent-unity doctor --json
Also check that the Unity package is installed and the Editor has finished compiling.
NoMoreRolls - full Play Mode video from a Unity game built with Hera-assisted Editor work.
Victor - Unity/C# developer with 6+ years of live-service MMORPG production experience.
GitHub: @NotNull92
Discord: Join the Hera community
Hera is free and licensed under Apache-2.0. If it saves you time, you can support development:
Control and verify a live Unity Editor through a local, low-token MCP server.
{ "mcpServers": { "io.github.notnull92-hera-agent-unity": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "HERA_MCP_ENABLED": "<value>" } } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Der Herausgeber nennt diese Umgebungsvariablen: HERA_MCP_ENABLED.
Hera Agent Unity läuft lokal über stdio.
Zuletzt geprüft: 2026-11-09. Control and verify a live Unity Editor through a local, low-token MCP server.