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 only resident surface is one small cacheable doc (~1k tokens) that stays flat no matter how many commands exist, versus an estimated ~4k–31k resident tokens for sampled Godot MCP servers.

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 / remove nodes, attach & detach scripts, wire resources, connect & disconnect signals. Editor node and signal writes are undoable steps (Ctrl+Z).
• Scripts & project — create scripts and scenes, 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, call helper methods, click controls semantically, inject real input and prove what was delivered, read the runtime UI tree, and assert on state.
• Proof-first QA — capture and analyze screenshots, compare captures locally, run requirement-covered QA scenarios, and get a one-shot runtime health verdict with game qa diagnose.
• Godot-native UI theme QA — measure spacing, type scale, color convergence, contrast, container structure, and decoration, then re-read live predicates and confirm the rendered result.
• Diagnostics — tail the effective Godot log with error/warning filters, expose unavailable logging evidence, and summarize problems without false-clean results.

New in v1.0.0 — a stable contract, Theme QA, and stronger proof

• Stable v1 CLI contract. Hera now freezes its documented stable command invocation, output streams, exit-code meanings, response field names, and JSON types for the v1 major line, backed by contract goldens, SemVer, and a written deprecation policy.
• Godot Theme resource tools. theme get and theme set read and update the colors, constants, and font sizes stored behind Godot's per-type Theme maps — data that ordinary resource property mutation cannot reach.
• Local screenshot comparison. screenshot diff compares captures without a live editor and reports dimensions, changed-pixel count and ratio, maximum channel delta, identity, and the exact changed bounding box, with a threshold for anti-aliasing wobble.
• Godot-native UI theme QA. The bundled workflow measures spacing, type scale, color convergence, WCAG contrast, container structure, and decoration. Safe mechanical fixes use existing project values and are verified against the live rendered result; structural and stylistic judgment remains report-only.
• More reliable editor discovery. Empty instance scans retry over bounded delays during Windows heartbeat replacement races, while repeated heartbeat failures still surface before the freshness window is at risk.
• Truthful, quieter diagnostics. diagnostics, output, and game qa diagnose report when log evidence is unavailable instead of returning a false clean result, while expected mid-write runtime file-exchange races no longer flood the Godot output.
• Compatible v0.9 → v1 upgrade. Upgrade the CLI and addon together, fully restart Godot, then run hera status and hera smoke --skip-game. Existing scenes, opt-in auth, discovery paths, and the transitional hera-agent-godot command alias remain compatible.

Command surface

status, instances, run / stop, scene, editor, script, project, classdb, node (read + write + resource/script wiring), signal, resource, theme, game (runtime inspect + input + input-log + set/call/click + assert + QA + screenshot), guidance, game_feel, output, diagnostics, eval, screenshot (capture + local diff), batch, and smoke — with --json (pretty) and --ids (paths only) 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, migration guide, 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