GDH

GDH makes AI coding agents actually good at Godot.

Coding agents that are excellent in web and systems codebases fall apart inside a Godot project. They have thin GDScript training data, so they hallucinate APIs. Godot's real validation loop lives inside the editor, so agents edit blind. The engine can print a fatal scene-parse error and still exit 0, so "the game ran" proves nothing. And everything an agent painstakingly figures out — how imports behave, how this project launches, which errors are noise — evaporates when the session ends.

GDH is a harness you install into a Godot repository. It gives Claude Code and Codex the project's real shape, wires Godot-native validation into their edit loop, and turns "I ran the game" into evidence you can audit.

Status: early and evolving. We build our own games with it daily at Skillcap Studio, but expect rough edges.

Quick Start

From the Godot project or repo you want GDH to manage:

npx -y @skillcap/gdh@latest setup

Then open your agent in that project and run:

/gdh-onboard

Setup detects your Godot project (including nested projects in monorepos), writes integration control and runtime knowledge under the git root's .gdh/, ignored machine state under .gdh-state/, and full target-specific guidance under the selected Godot project's AGENTS.md and .gdh/guidance/. It installs agent skills and MCP tools and pins the GDH version so future updates migrate deliberately instead of drifting underneath the project.

What Your Agent Gets

Mistakes caught close to edit time, not left to review. Managed hooks check supported saved .gd edits made through configured edit/write tools against the real Godot LSP. Deleted files, non-GDScript files, missing or untrusted hooks, timeouts, and degraded diagnostics remain explicit gaps; hook silence is never evidence. A final pinned authoring check produces pass/block evidence for handoff.

Godot knowledge at the point of use. Search and fetch official Godot docs pinned to your engine version, plus curated guidance for the traps the official docs don't cover: import churn, autoload order, scene-tree timing, @tool scripts.

Scene authoring through a real editor, not text munging. The Editor Bridge lets agents inspect and author scenes, resources, and animations through Godot's own APIs, backed by a managed headless editor process — instead of hand-editing .tscn files and hoping.

Reproducible engine selection without a new GDH lockfile. Per-call, environment, and target-local editor overrides keep priority. Otherwise, when a project commits a resolving .ugrc within its integration root, it supersedes the machine-global GDH default: GDH delegates selection to ug, launches its own Godot processes through ug exec --, and reports the concrete pinned engine in status. Healthy projects without a pin keep the existing global/default discovery path without extra setup prompts.

Runs that produce evidence, not vibes. How your game launches stays project-owned: a committed runbook records the real commands, env, ready signals, and cleanup. Around a launch, the runtime bridge exposes scene-tree state, node properties, bounded input actions, on-demand screenshots, and performance sampling — and run artifacts land under .gdh-state/runs/ where humans and agents can audit them.

Knowledge that accumulates. What an agent learns about your project routes back into committed guidance and structured state, so the next session starts smarter instead of rediscovering the same facts.

Requirements

• Node.js 24 or newer
• A git working tree (GDH resolves project roots through git; worktrees are supported)
• A Godot 4.4–4.7 project (managed LSP authoring checks need Godot 4.5.2+)
• Claude Code or Codex
• Optional: use-godot (ug) v0.1.2+ with a project .ugrc (recommended for reproducible engine selection on upstream-supported hosts), or a local Godot editor binary via GDH_GODOT_EDITOR_BIN; Docker remains optional when your project's run workflow uses containers

GDH is developed and proven on macOS; see the runtime support matrix for the full host contract.

Scope, Honestly

GDH's support claims are deliberately bounded, and the runtime support matrix is the source of truth for what is shipped, what is partial, and what is out of scope. GDH does not promise free-form gameplay automation, generic visual automation, or a hosted control plane — it promises that agents working on your Godot project validate against the real engine and show their evidence.

Documentation

• Install and update — setup, monorepo layout, updating managed projects
• Advanced CLI usage — compact gdh command index
• Editor Bridge — Godot-native scene and resource authoring
• Runtime support matrix — exactly what is and isn't supported
• All docs

License

MIT