hera-agent-unity

<div align="center">

<img src="docs/assets/hera_logo.png" width="50%" alt="hera-agent-unity">

<br>

[![Release](https://img.shields.io/github/v/release/NotNull92/hera-agent-unity?style=flat-square&logo=github&color=00d4aa)](https://github.com/NotNull92/hera-agent-unity/releases)
[![GitHub stars](https://img.shields.io/github/stars/NotNull92/hera-agent-unity?style=flat-square&logo=github&label=stars&color=181717)](https://github.com/NotNull92/hera-agent-unity/stargazers)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square&color=blue)](LICENSE)
[![Go](https://img.shields.io/badge/go-%5E1.25-00ADD8?style=flat-square&logo=go)](https://go.dev)
[![Unity](https://img.shields.io/badge/unity-2022.3%2B-000000?style=flat-square&logo=unity)](https://unity.com)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-ff69b4?style=flat-square)]()

**Low-token Unity Editor control for AI coding agents.**

<sub>Let Codex, Claude, Cursor, Copilot, and AntiGravity inspect and change your live Unity project — no MCP setup for the default CLI path, no Python server.</sub>

<br>

[Start in 60 seconds](#quick-start) · [Install](#install) · [UI systems](#ui-systems) · [Commands](#commands) · [Full docs](docs/COMMANDS.md)

<sub>[What's new](#whats-new) · [Verification](#ultra-hera) · [Agent rules](#add-project-rules-for-agents) · [FAQ](#faq)</sub>

**English** · [한국어](README.ko.md)

</div>

---

## 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:

| You want the AI to... | Hera lets it... |
|:---|:---|
| See if Unity is open | ask the real Editor |
| Run C# code | run it inside your loaded project |
| Check console errors | read the actual Unity Console |
| Enter Play Mode | press Play and wait |
| Create or edit objects | use Unity APIs safely |
| Build UI | create real Unity UI objects and capture the result |
| Verify UI input | send Unity EventSystem events without relying on screen coordinates |

The AI does not need to guess from stale training data. It can inspect the real Editor, act on it, and check the result.

```text
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.

```bash
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. The production-default CLI path needs no MCP config or special
agent plugin. CLI `v0.1.0+` also includes an experimental, default-off stdio MCP
adapter for intentionally configured MCP clients. See
[docs/MCP.md](docs/MCP.md) for setup and compatibility boundaries.

---

## What's New

### v0.1.3 - package-backed MCP discovery

This follow-up patch publishes the existing default-off stdio MCP adapter
through the official MCP Registry without changing the Unity Connector or
normal CLI path.

| Release change | What it means |
|:---|:---|
| Official MCP identity | `io.github.NotNull92/hera-agent-unity` exactly matches the case-sensitive GitHub OIDC namespace and links the registry entry to npm. |
| Reproducible local launch | Registry clients receive the fixed `mcp --transport stdio --profile core` arguments and `HERA_MCP_ENABLED=1` opt-in. |
| Ordered trusted publication | GitHub Actions publishes npm first, then uses GitHub OIDC and a checksum-pinned publisher for the MCP Registry. |
| Connector unchanged | The released Unity package remains Connector 0.0.80; CLI and Connector versions stay independent. |

### v0.1.1 - hardened contracts, recovery, and release evidence

This release tightens the completed CLI + optional MCP architecture without
replacing its proven Unity execution core.

| Release change | What it means |
|:---|:---|
| Versioned execution metadata | Current single-command clients send `hera.execution/1`; unsupported future versions fail before approval, journaling, or Unity execution. |
| Stronger recovery boundaries | Stale catalogs, abandoned ledger entries, partial Hera Settings reads, stale config locks, and uncertain mutation timeouts now fail or recover explicitly. |
| Smaller Compact discovery | `tool_describe` can return one action contract instead of an entire multi-action tool; the largest measured case is about 92% smaller. |
| Repeatable release gates | Generated Go/C# contract drift, five Unity compile buckets, isolated NUnit package tests, race tests, and catalog payload budgets have reproducible checks. |
| Connector 0.0.80 | The UPM package carries the matching runtime hardening and release-gate changes; CLI and Connector versions remain independent. |

The normal CLI remains the production default. MCP remains optional,
default-off, and stdio-only.

### v0.1.0 — safe multi-Editor targeting and an optional MCP adapter

This release completes the M0-M17 adapter migration without replacing the
normal CLI. MCP is shipped as an experimental, stdio-only, environment-gated
option; the typed CLI and localhost Unity Connector remain the production
default.

#### Why make this migration?

More AI applications now speak MCP as a common way to discover and call tools.
Hera already had a small, efficient CLI and a proven Unity execution path, so
rebuilding the product around MCP would have duplicated that work and changed a
workflow that existing users rely on. Instead, v0.1.0 adds a thin translator at
the edge: an MCP-capable AI can speak its familiar protocol while Hera keeps
executing the same validated CLI and Connector operations underneath.

Think of the CLI as Hera's compact dedicated remote control. The MCP adapter is
a small plug converter that lets a different device use that remote; it does
not replace the remote with a larger control panel.

#### How does it work?

The path is `AI client → optional MCP adapter → existing Hera execution core →
localhost Connector → the selected Unity Editor`. The adapter searches and
describes tools, validates the requested operation, applies the same safety
policy, and then hands the call to Hera's existing execution path. It does not
open Unity to the network, replace the Connector, or silently relax approvals.
Unsupported approval or operation-ledger features fail closed instead of
guessing that an operation is safe.

#### Does it make Hera more accurate?

MCP by itself does not make an AI smarter, and the adapter does not use a
different Unity execution engine. Accuracy improves at the delivery layer: an
exact normalized project path prevents a request from drifting to another open
Editor; strict live contracts reject malformed or outdated arguments; and a
fresh heartbeat distinguishes a domain reload, an Editor restart, a lost
target, and a port that another project has taken over. Operation IDs and the
Connector ledger also prevent an uncertain response from becoming the same
mutation twice.

In everyday terms, Hera now checks both the full delivery address and the
receipt before acting. That reduces wrong-project calls, invalid requests, and
duplicate changes. It does **not** guarantee that the AI's design decision is
correct, replace Unity tests, or prove a numerical accuracy improvement. No
repository benchmark currently supports an “X% more accurate” claim; the
measurable promise is narrower: detect more ambiguous or stale connection
states and stop safely instead of guessing.

The first retained end-to-end game-creation run is the
[Crystal Forge real-world benchmark](docs/benchmarks/user-scenario/crystal-forge-6000.3.5f2.md).
It reached the correct playable result only after several repairs; first
attempt success was **not** achieved. It is a regression baseline, not an
MCP-versus-CLI A/B result or proof of higher model accuracy.

#### Does it use more tokens?

The normal CLI path has no new token cost because it has not changed. MCP adds
some unavoidable protocol metadata, so token use is **not guaranteed to be
identical** and depends on the AI client and the task. Hera limits that overhead
in two ways: Profile exposes a small, stable native surface, while Compact MCP
registers only three gateway tools — search, describe, and call — and fetches a
tool's details only when they are needed. The large Full surface remains an
explicit diagnostic option rather than the default.

There is not yet a repository benchmark that proves exact CLI/MCP token parity.
The design goal is therefore honest and narrower: preserve the CLI's current
cost, and make MCP compatibility pay as little up-front context cost as
possible.

#### Why borrow Compact MCP if Hera is CLI-first?

Hera's principle is low-token, verifiable Unity control — not loyalty to one
protocol. Refusing MCP completely would isolate Hera from compatible AI hosts;
adopting a conventional “register every tool” MCP design would send a large
catalog of names, descriptions, and schemas into context before most of it was
needed. v0.1.0 deliberately uses MCP only as the outside language and keeps the
CLI as the production core. Compact exposure preserves the original philosophy
by making compatibility on-demand instead of turning compatibility into a
permanent token tax.

| Release change | What it means |
|:---|:---|
| Project-aware Editor selection | Full normalized project paths identify Editors; ports are treated as temporary endpoints and ambiguous matches fail. |
| Safe response-loss recovery | Hera detects domain reloads, Editor restarts, lost targets, and port reuse before any eligible retry. Non-idempotent mutations are never blindly repeated. |
| Experimental MCP adapter | `HERA_MCP_ENABLED=1 hera-agent-unity mcp` exposes Profile, Compact, Full-safe, approval, op