📦 hera-agent and hera-agent-pro have been unified into hera-agent-unity. All features are now bundled under MIT license. View new repo →
Open Source · MIT · Unity 6+

AI guesses at Unity.
Hera sees for itself.

LLMs remember last year's Unity.
You pay that gap in tokens, every time.
hera-agent-unity touches this Unity, right now.

Get it on GitHub → ↓ 5-min install guide 
// Verify the type AI guessed — directly in Unity
hera-agent-unity describe_type UnityEditor.EditorApplication

// Catch syntax before run — cut one retry
hera-agent-unity exec --check "return Camera.main.name;"

// Enter Play Mode + check errors in one go
hera-agent-unity editor play --wait && hera-agent-unity console --type error
hera-agent-unity

Quick Start

5 minutes to install, 1 second to first command

1

Install CLI

curl -fsSL https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.sh | sh
irm https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.ps1 | iex
go install github.com/NotNull92/hera-agent-unity@latest
2

Install Unity Connector

Package Manager → Add package from git URL

https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector

Unity 6 (6000.0+) required. Connector starts automatically.

3

First command

hera-agent-unity status              # check connection
hera-agent-unity editor play --wait  # enter Play Mode
hera-agent-unity exec "return Camera.main.name;"  # run C#
4

Connect AI agent

hera-agent-unity doctor --agent-rules >> CLAUDE.md           # Claude Code
hera-agent-unity doctor --agent-rules >> AGENTS.md           # Codex
hera-agent-unity doctor --agent-rules >> .cursor/rules/hera-agent-unity.mdc   # Cursor
hera-agent-unity doctor --agent-rules >> .github/copilot-instructions.md  # Copilot

Works with any AI coding agent. Pure CLI — not tied to MCP.

Problem

AI doesn't know your Unity

🎲

API guessing

LLMs memorize last year's Unity API. New methods, deprecated properties, project-specific code — they don't know.

🔁

Run-fail-retry loop

Write code → compile error → fix → rewrite. 3–5 times per session is normal.

🌫️

Console error inference

AI reads error logs and says "this is probably the issue." No certainty.

📊

Performance guessing

Profiler requires GUI clicks. AI can only say "this is probably the bottleneck."

Features

24 tools, single binary, zero runtime dependencies

hera-agent-unity Control Unity Editor from the terminal
core

exec — runtime C# execution

Run arbitrary C# code inside Unity Editor. Full API access, compile cache for instant re-invocation.

hera-agent-unity exec "return Camera.main.name;"
core

exec --check — syntax check before run

Check syntax without executing. Filters out one round of AI's "run → fail → retry."

hera-agent-unity exec --check "return Camera.main.name;"
core

editor — Play Mode control

play, stop, pause, refresh, compile. --wait flag blocks until state is confirmed.

hera-agent-unity editor play --wait
core

console — filtered logs

error/warning/log filter, stacktrace control, clear. All in terminal — no GUI console needed.

hera-agent-unity console --type error
core

scene — scene info, load, save, list, close

Active scene info, Build Settings scene list, additive load, save, close.

hera-agent-unity scene load Main --mode additive
core

test — EditMode/PlayMode

Unity Test Framework integration. Filtering, result file poll, domain-reload safe.

hera-agent-unity test --mode PlayMode --filter MyTest
core

profiler — performance analysis

Profiler hierarchy without GUI clicks. Sort, depth, threshold — pull hotspots directly.

hera-agent-unity profiler hierarchy --depth 5 --sort self
core

screenshot — screen capture

Scene View or Game View capture. For automation docs, CI screenshot comparison.

hera-agent-unity screenshot --view game
core

batch — multiple commands at once

Bundle multiple commands in a JSON file. Reduce round trips in CI/CD.

hera-agent-unity batch --file deploy.json
introspection

describe_type — live API inspection

Pull types, methods, signatures from running code. Live state — not LLM training cutoff guesses.

hera-agent-unity describe_type UnityEditor.EditorApplication
introspection

find_method — method search

Search methods in loaded assemblies via reflection. Namespace filter, signature check.

hera-agent-unity find_method Refresh --namespace UnityEditor
introspection

list_assemblies — assembly list

List all assemblies loaded in current project. Version, path included.

hera-agent-unity list_assemblies
introspection

unity_docs — offline Unity docs

Query Unity ScriptReference offline. No network needed, exact API info for your Unity version.

hera-agent-unity unity_docs GameObject
gameobject

manage_gameobject — GameObject CRUD

Create, delete, rename, set parent, activate/deactivate. HierarchyPath for exact path targeting.

hera-agent-unity manage_gameobject create --name Player --parent /World
gameobject

find_gameobjects — object search

Search GameObjects by name, tag, component. Include inactive option.

hera-agent-unity find_gameobjects --name Enemy --inactive
gameobject

manage_components — component CRUD

Add, remove, modify components. SerializedProperty path for deep property access.

hera-agent-unity manage_components --target Player --add Rigidbody
asset

manage_material — material editing

Shader property query, material create/modify. Color, texture, vector value setting.

hera-agent-unity manage_material --create NewMat --shader URP/Lit
asset

manage_prefab — prefab management

Prefab create, instantiate, component add/remove. Headless — no PrefabStage needed.

hera-agent-unity manage_prefab --create-from Player --path Assets/Prefabs
asset

describe_shader — shader property query

Check shader property names, types, display labels, ranges. Essential before material editing.

hera-agent-unity describe_shader URP/Lit --list
asset

manage_asset_import — import settings

Modify TextureImporter, ModelImporter settings via SerializedProperty directly.

hera-agent-unity manage_asset_import --path Assets/Textures --set textureType Sprite
ui

manage_ui — uGUI authoring

Create Canvas, Panel, Button, Text and other uGUI elements. RectTransform anchor/pivot/preset setting.

hera-agent-unity manage_ui create --type button --text "Start"
package

manage_packages — UPM package management

Install, remove, embed packages. Git URL, registry, local file all supported.

hera-agent-unity manage_packages add com.unity.cinemachine
custom

Custom tools ([HeraTool])

Tag a C# class with [HeraTool] and it becomes a CLI command automatically. Easily add project-specific tools.

hera-agent-unity list # check registered tools

How It Works

Hide what's complex. Show what's simple.

Terminal
Single Go binary
hera-agent-unity exec "..."
→
HTTP
localhost:8090
POST /command
→
Unity Editor
C# Connector auto-starts
[HeraTool] execution

When Unity Editor opens, the C# Connector automatically starts a localhost HTTP server.
The Go CLI discovers Unity via heartbeat files, copies commands as JSON, and executes them.
Even script compilation domain reloads don't break the connection — the server auto-restarts.

Benchmark

Measured against real AI agent usage patterns

~1,622
tokens for 50 exec calls
70%
responses under 5 bytes
$0.03
per Claude Sonnet session

Direct measurement when calling hera-agent-unity as a tool from AI agents (Claude Code, Codex, etc.).

Realistic usage pattern: 50 exec C# calls = total 6,568 bytes (~1,622 tokens).
70% of responses are under 5 bytes (OK\n) — tool cost is effectively noise.
Most tokens go into the C# code the agent writes (input).

See Benchmark report for detailed measurement environment and scenarios.

FAQ

Unity 6000.0 (Unity 6) or later is required. Unity 2022 LTS and 2021 LTS are not supported.

No. It's a single Go executable. The Unity side installs as a UPM package — that's it. No runtime or extra server to keep running.

Yes. When scripts recompile the server restarts too, but hera-agent-unity finds the new port automatically. Nothing to touch.

Yes. hera-agent-unity works with any AI coding agent — Claude Code · Codex · Cursor · Copilot · Continue.dev. Append the lean rules to your agent's rules file:

hera-agent-unity doctor --agent-rules >> CLAUDE.md           # Claude Code
hera-agent-unity doctor --agent-rules >> AGENTS.md           # Codex
hera-agent-unity doctor --agent-rules >> .cursor/rules/hera-agent-unity.mdc   # Cursor
hera-agent-unity doctor --agent-rules >> .github/copilot-instructions.md  # Copilot

Full usage guide is in the repo root AGENT.md (~3.4K tokens). hera-agent-unity is a pure CLI — not tied to MCP. Call it from any shell or script.

Migrate to hera-agent-unity. All Pro features are now bundled under MIT license. Just change CLI command from hera-agent → hera-agent-unity. Update UPM URL to hera-agent-unity.git.

Direct measurement from AI agents (Claude Code, Codex, etc.): 50 exec C# calls = ~1,622 tokens total. At Claude Sonnet pricing that's under $0.03 per session — even 5 sessions a day for 30 days stays under $5/month. 70% of responses are under 5 bytes (OK\n), so tool cost is effectively noise. Most tokens go into the C# code the agent writes (input).

Tag a C# class with [HeraTool] and it's picked up automatically. Define a Parameters class for args and put your logic in HandleCommand. Run hera-agent-unity list to verify registration.

So the next line doesn't die at compile time

5 minutes to install. 1 second to the first command. The next AI step moves from guessing to measuring.

Get it on GitHub → ↓ Install guide