hera-agent-godot

English · 한국어

Hera gives agents eyes, hands, and proof in the live Godot editor.

Assembled, ran, and QA-tested a live Godot game entirely from the shell — build the scene, run it, read the moving player, inject input and verify the game reacts, recolor a running node. The whole session is ~1,170 tokens of tool output: compact JSON by default, no tool-schema preload.

A low-token CLI that lets AI coding agents inspect and control a live Godot 4.7+ editor in real time — read the output/errors, run a scene, walk and edit the node tree, evaluate GDScript, and more. The agent acts on the real editor and checks the result instead of guessing from stale training data.

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 product identity is intentionally simple: live editor truth, low-token control, proof-first QA. See docs/IDENTITY.md for the language and design principles that keep new features aligned.

Sibling of hera-agent-unity — same low-token, shell-native philosophy, designed for Godot, not ported.

Current release baseline: v1.1.0

v1.1.0 is the repository tag and addon manifest baseline. It is a minor release on the v1 contract: new commands and experimental fields, no intended break of documented stable JSON.

Highlights since v1.0.0:

• Language selection: create, inspect, open, and attach .gd or .cs by filename; C# needs Godot .NET and a loaded assembly. See docs/CSHARP_SUPPORT.md.
• Play clock and input: game clock for SceneTree.paused / Engine.time_scale / one-frame step; joypad and axis injection; physics-frame game input sequence.
• Scene and scripts: undoable node reparent; script validate runs the connected editor's engine on a disk script.
• Honest runtimes: game --pid selects one live game; screenshots report live capture size; expired editor heartbeats are stale; parallel games that share user:// are flagged.
• Safer mutations: subtree ownership on undo, batched resource/theme validation, fail-closed token startup, and QA scenario preflight.

Upgrade the CLI and addon together and fully restart Godot. Release notes and Asset Store packaging: docs/releases/v1.1.0-asset-store-upload.md. The v1 compatibility promise remains docs/CONTRACT.md.

Nonvisual CI (configured tier)

The nonvisual CI recipe defines a pinned, Godot 4.7-only nonvisual lifecycle: static script checks stay headless; the live editor and game run inside an isolated virtual display so the deterministic runtime-logic scenario can execute. It excludes screenshots, visual UI, renderer output, and window/input claims, and does not extend live runtime coverage to Godot 4.2–4.6.

Remote GitHub Actions verification passed on 2026-07-13 at commit 5c0ba65. The successful run includes the nonvisual editor→game lifecycle and its requirement-covered runtime-logic scenario.

Low-token, measured

The "MCP-grade reach, fewer tokens" claim — with numbers:

	Hera (CLI)	Godot MCP servers (~41–155 tools)
Tool schemas resident per turn	0	~4k–31k tok (grows with tool count)
Surface the agent loads	one doc, ~1.0k tok — cacheable & flat	full tool list, re-sent each turn
Per-action response	compact JSON — status ≈48 tok, node get ≈186 tok	JSON, often pretty

Hera figures are measured on a live Godot 4.7 editor; the MCP column is an estimate from sampled public Godot MCP tool counts (~41–155 tools) × ~100–200 tok per tool schema. Method, caveats, and a reproducer: docs/LOW_TOKEN.md.

Command surface

The v1.1.0 CLI/addon surface includes: status, instances, run/stop, scene, editor, script (including validate and .gd/.cs create), project, classdb, node (read + write + reparent + resource/script wiring), signal, resource (get/uid/list/set/create/resave/update-uids/export-mesh-library), theme (get/set for Theme resource items), game (runtime inspect + UI audit + clock + input + joypad/axis + sequence + input-log + set/call/click + assert + QA + screenshot), guidance, game_feel, output, diagnostics, eval, screenshot (capture + local before/after diff), batch, and smoke, with --json/--ids output modes. See docs/COMMANDS.md for the command reference and docs/ROADMAP.md for release history and Asset Store packaging status.

Check on-disk GDScript with hera script validate res://Player.gd. Validation uses the connected editor's engine in a bounded headless process, prints the engine output as JSON, and exits nonzero on failure. It does not compile C# or certify warning-free code; loading dependencies can execute code. Replay input actions with hera game input sequence --file events.json, where the array contains { "frame": 0, "action": "ui_accept", "pressed": true } events. Frames are relative physics frames; held actions are released on exit. See the command reference for timing limits and QA examples.

Choose GDScript or C# by the script filename: hera script create res://Player.gd or hera script create res://Player.cs --ready --export Speed:float=3.5f. Optional --lang gdscript|csharp must agree with the extension. C# creation, opening, and attachment require Godot .NET; status.csharp_supported reports editor support, not whether the .NET SDK is installed. Build and reload the C# assembly before attaching a new script. Hera does not build or generate solution files, and C# inspection reflects the loaded assembly, which may be stale. The addon stays GDScript, and eval uses GDScript expressions in either project. See C# support for setup and limitations.

Externally launched and parallel game processes can be selected independently from the editor: list them with hera game instances, then use hera --instance <EDITOR_PID> game --pid <GAME_PID> tree (or any other game/QA subcommand). Without --pid, editor-play selection remains the default and ambiguous targets still fail. --instance and --pid select processes; they do not isolate user:// save files. Runtime screenshots report the live viewport size and are not upscaled to the project resolution. Expired editor heartbeats show up as stale on hera instances instead of looking like a missing editor. The Hera runtime inspector stays available for editor play but is removed from exported project settings.

Install

CLI — via a package manager:

# Windows (Scoop)
scoop bucket add hera-agent-godot https://github.com/NotNull92/hera-agent-godot
scoop install hera

# macOS / Linux (Homebrew)
brew install NotNull92/hera/hera

# Any platform with Node.js 18+ (npm)
npm install -g hera-godot
# or zero-install: npx hera-godot status

Or a one-liner that fetches the latest release binary:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/NotNull92/hera-agent-godot/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/NotNull92/hera-agent-godot/main/install.ps1 | iex

Set HERA_VERSION to pin a tag and HERA_BIN_DIR to change the target dir. Or build from source: go build -o hera . (Go 1.25+). Check it with hera version. Windows winget distribution is intentionally retired: no winget-pkgs submission exists or is planned. See the recorded decision in packaging/README.md.

Addon — download hera-agent-godot-addon.zip from the latest release, unzip it into your Godot project root (creating addons/hera_agent_godot/), and enable it under Project → Project Settings → Plugins.

Agent integrations

Each kit gives an agent one compact Hera workflow instead of a large tool schema. Install the CLI and enable the addon first.

• Claude Code: inside Claude Code, add this repository as a marketplace and install the plugin:

  /plugin marketplace add NotNull92/hera-agent-godot
  /plugin install hera-godot@hera-agent-godot
  /reload-plugins
  

  The live-editor skill auto-invokes for Godot editor work; invoke it directly as /hera-godot:live-editor when desired. To test a local checkout without adding a marketplace, run claude --plugin-dir ./integrations/claude-code/hera-godot.

• Codex: inside a terminal, add this repository as a Codex plugin marketplace and install the plugin:

  codex plugin marketplace add NotNull92/hera-agent-godot
  codex plugin add hera-godot@hera-agent-godot
  

  The bundled live-editor skill auto-invokes for Godot editor work. To test a local checkout, run codex plugin marketplace add <checkout-dir> and remove it afterwards with codex plugin marketplace remove hera-agent-godot.

• Cursor: copy integrations/cursor/hera-godot.mdc to <your-project>/.cursor/rules/hera-godot.mdc. It is an Agent Requested project rule, so Cursor loads it when live Godot work is relevant.

• Other coding agents: append integrations/AGENTS.md to the target project's AGENTS.md.

Each agent-facing document stays below the ~1k-token surface budget that supports Hera's low-token design; Claude Code and Codex share the same live-editor skill.

How it works

Go CLI  ──HTTP /rpc──▶  Godot editor addon (@tool EditorPlugin, GDScript)
 (cmd/, internal/)        (addons/hera_agent_godot/)
        ▲                          │
        └── scans ~/.hera-agent-godot/instances/ ◀── Heartbeat

• CLI (Go): discovers the editor, sends one compact JSON request per command.
• Addon (GDScript): runs a localhost HTTP server, executes each request on the editor main thread via EditorInterface.

See docs/ARCHITECTURE.md for the full design, docs/COMMANDS.md for the command surface, and docs/ROADMAP.md for release history.

Repository layout

addons/hera_agent_godot/  the distributable Godot 4.7+ addon (GDScript)
project.godot, scenes/    dev host project — the CLI's run/save/screenshot target
cmd/                      Go CLI commands (status, instances, run/stop, scene, editor, script, project, classdb, node, signal, resource, theme, game, guidance, game_feel, output, diagnostics, eval, screenshot, batch, smoke)
internal/                 client / discovery / protocol
docs/                     ARCHITECTURE, COMMANDS, ROADMAP, release notes, prompt-game guidance
integrations/             compact Claude Code, Cursor, and AGENTS.md harness kits

Requirements

• Go 1.25+ (CLI)
• Godot 4.7+ standard build recommended (addon). Verified minimum is 4.2: the addon loads and answers the CLI on 4.2–4.6 (spot-checked) — see docs/SUPPORT_MATRIX.md.

Security

Undoing node removal or reparenting restores descendant scene ownership. Resource/theme edits validate all requested values before applying them. Runtime UI targeting and audit use viewport coordinates, including canvas and camera transforms. Scenario QA rejects unreadable diagnostics; omitting max_warnings allows warnings, while an explicit 0 requires none. QA run steps wait for the requested play/stop state; state-only reads return immediately.

The bridge binds 127.0.0.1 only and rejects browser-origin requests. Optional shared-token auth locks it to clients that know a secret (~/.hera-agent-godot/token or HERA_AGENT_GODOT_TOKEN). Threat model and setup: docs/SECURITY.md. An existing token that cannot be read prevents bridge startup. HTTP replies use bounded partial writes with a separate five-second write deadline.

Sibling: hera-agent-unity

Working in Unity too? hera-agent-unity brings the same low-token, shell-native philosophy to the Unity Editor — read console errors, run C#, enter Play Mode, manage GameObjects, build UI, and run tests, all in compact, agent-friendly output. Across both engines, your agents get one consistent way to drive each.

Support

Hera is free and MIT-licensed. If it saves you time, you can support development:

Join the Discord community

License

MIT — see LICENSE.