Hera Agent Godot lets AI coding agents inspect and control a live Godot editor in real time — instead of guessing scene structure from stale training data, the agent acts on the real editor and checks the result. Verified on every stable from Godot 4.2 to 4.7.

This Asset Library entry is the editor addon (the in-editor bridge). The companion hera CLI lives on GitHub and is what the agent actually runs.

Why a CLI, not MCP?

Godot already has a healthy MCP-addon ecosystem — Hera makes the opposite bet on purpose. MCP servers pay for breadth in tokens: dozens to 100+ tool schemas plus verbose JSON responses sit in the agent's context every turn.

Hera delivers MCP-grade reach over the live editor as a compact-JSON-by-default CLI — one command per action, minimal tokens, and it works with anything that can run a shell command (pipes, batch, CI, any agent), not just MCP clients. The agent loads zero tool schemas. The driver card and command reference are cacheable markdown; they grow with the surface, unlike MCP schemas that sit in every turn.

What the agent can do

• Read the editor — live status, scene tree, node properties, open scenes, selection, focused scripts, resources, Theme items, and ClassDB metadata.
• Edit the scene — add / instance / set / reparent / remove nodes, attach & detach scripts, wire resources, connect & disconnect signals. Editor node and signal writes are undoable steps (Ctrl+Z).
• Scripts & project — create GDScript or C# by filename, validate on-disk GDScript with the connected editor's engine, manage project files and folders, scan/reimport resources, refresh UIDs, and set the main scene.
• Inspect and edit Themes — read or update Godot Theme colors, constants, and font sizes through the engine's per-type Theme maps.
• Run GDScript — evaluate an expression against the edited scene through an EditorInterface proxy.
• Drive a running game — inspect and mutate the runtime tree, pause and step the play clock, click controls, inject keyboard/mouse/joypad input or physics-frame sequences, read the runtime UI tree, and assert on state.
• Proof-first QA — capture and analyze screenshots at the live viewport size, compare captures locally, run requirement-covered QA scenarios, and get a one-shot runtime health verdict with game qa diagnose.
• Diagnostics — tail the effective Godot log with error/warning filters, summarize problems without false-clean results, and opt into bounded editor-session logs.

New in v1.2.0 — reliability, receipts, and compact observations

• Mutation gate. Overlapping editor mutations and sensitive reads fail editor_busy. Batches keep ownership through import. Status and buffered editor logs stay available.
• Operation receipts. operation submit|status|cancel records guarded node set and session-targeted game set/call. Pre-dispatch refusals are rejected/not_applied with a stable error_code. Exit 0 means the receipt was obtained, not that the mutation succeeded.
• Guarded node sets. --expected / --snapshot / --verify refuse stale session, scene, node, or property observations before the setter.
• Editor log evidence. output / diagnostics --source editor use a verified collector and session cursors. Default file logs name source: file so clean is not a claim about the Output panel.
• Linked evidence. Opt-in --evidence on captures, scene save, resource set, and script validate. Unavailable observations fail evidence-enabled QA.
• Compact defaults. status omits the experimental capability map unless --capabilities. Operation receipts omit retention and echoed evidence.response unless --verbose. --ids prints Control paths from game ui tree.
• Honest batch params. Non-object batch child params are not rewritten to {}; the addon rejects them.

Upgrade the CLI and addon together, fully restart Godot, then run hera status and hera smoke --skip-game. Existing scenes, opt-in auth, and the transitional hera-agent-godot alias remain compatible. Experimental command shapes may still evolve; documented stable fields keep the v1 promise.

Command surface

status (plus --capabilities), operation, instances, run / stop, scene, editor, script (including validate and .gd/.cs), project, classdb, node (read + write + reparent + resource/script wiring + guarded set), signal, resource, theme, game (runtime inspect + clock + input + joypad/axis + sequence + input-log + set/call/click + assert + QA + screenshot), guidance, game_feel, output, diagnostics (--source file|editor), eval, screenshot (capture + local diff + opt-in evidence), batch, and smoke — with --json and --ids output modes plus --instance and --timeout global flags; compact JSON is the default.

How it works

The addon is an @tool EditorPlugin that runs a localhost HTTP server and advertises the editor to the CLI via ~/.hera-agent-godot/instances/. The Go CLI discovers the editor and sends one compact JSON request per command, executed on the editor main thread through EditorInterface. No cloud and no account — everything stays on localhost, optionally behind the shared token.

Install

1. Use any Godot 4.2–4.7 stable build (4.7 recommended — it gets the full QA treatment; see docs/SUPPORT_MATRIX.md in the repo).
2. Copy hera_agent_godot/ into your project's res://addons/.
3. Enable Project → Project Settings → Plugins → Hera Agent Godot.
4. Grab the hera CLI from GitHub (one-line installer, npm, brew, scoop, or go build) and start driving the editor from your agent.

License

MIT-licensed — source, output contract, support matrix, C# notes, agent plugins, and the measured low-token methodology all live on GitHub.

Repo

If Hera saves your agent tokens, a star helps other Godot devs find it 🌟 github.com/NotNull92/hera-agent-godot

Links

• 🛒 Godot Asset Store: store.godotengine.org/asset/notnull92/hera-agent-godot
• 📦 npm: npmjs.com/package/hera-godot
• 🍺 Homebrew tap: github.com/NotNull92/homebrew-hera
• 📺 YouTube — Indie Alchemist: youtube.com/@IndieAlchemist
• 💬 Discord community: discord.gg/QBzEVuYwK
• 🎮 Unity sibling — hera-agent-unity: github.com/NotNull92/hera-agent-unity
• ☕ Support on Ko-fi: ko-fi.com/notnull92