gda — Godot Automation for AI Agents

Read this in: 简体中文 · Español · 日本語

Product overview · CLI, Agent Skill, or MCP? · Playable demos · PyPI

Build and verify Godot projects with AI coding agents, shell scripts, and CI. gda provides Godot automation with headless validation as well as live runtime inspection and control through a CLI, a bundled Agent Skill, or an MCP server, returning structured results agents can act on.

gda provides two complementary modes for this build-and-verify workflow:

• Headless — create and edit project content, compile scripts, validate and boot scenes, analyze project structure, and export builds without an editor plugin or daemon.
• Live — inspect and drive the running game through a per-project daemon: runtime tree and state, input simulation, frame capture, logs, errors, and performance.

gda is pre-1.0: every command works end to end today, but the command surface may still change before 1.0.

Contents

• Why gda?
• Capabilities at a glance
• Installation
• Quick start
• Choose your integration
• How it works
• Command reference
• Configuration
• Contributing
• License

Why gda?

• Verification across the game development lifecycle. Headless validation confirms project readiness; Live operations return runtime evidence about actual behavior.
• Structured results and discoverable schemas. With --json, each command emits exactly one result object on stdout. Typed input and output models also power --schema and the generated MCP tool surface.
• Godot-native bounded context and ubiquitous language. gda uses a single Godot-aligned operation model and vocabulary, giving agents consistent terms for project content and runtime state.
• Operate reliably in restricted environments. Redirect user data and logs to writable locations, isolate concurrent runs, and return typed environment failures before Godot crashes. This makes it easier for agents to work in sandboxes.
• Three complementary access paths. Run the CLI directly from an agent, shell, or CI; install the bundled Agent Skill for reusable guidance; or expose the same operations as MCP tools. See CLI, Agent Skill, or MCP? for comparison and tradeoffs.
• Bounded automation with actionable failures. Timeouts, bounded output, typed failures, diagnostics, and mutation reports help agents decide what happened and how to recover.

These capabilities were refined while building a real game, with the work documented in a public dogfooding record.

Capabilities at a glance

| Goal | What gda provides | Start with | | --- | --- | --- | | Build Godot project content (Headless) | Create and edit scenes, nodes, scripts, resources, project settings, shaders, and themes | scene / node / script / resource / project / shader / theme | | Verify project readiness (Headless) | Compile scripts, validate dependencies, boot scenes in a bounded preflight, analyze project structure, and export builds | script validate / scene validate / scene preflight / project / export | | Verify runtime behavior (Live) | Read runtime state, call declared methods, simulate input, capture frames, collect logs and errors, and sample performance | gda daemon start, then game / input / screen / diag / logger / perf | | Connect an AI coding agent | Use direct CLI execution, reusable Agent Skill guidance, or MCP tool discovery and calling | gda / gda skill / gda-mcp | | Run reliably in automation | Receive structured results, typed schemas and failures, bounded execution, isolated logs, and actionable diagnostics | --json / --schema / --user-data-root / timeouts |

Installation

Requirements: Python 3.13+ and a Godot binary — 4.4+ for Headless operations, 4.6+ on macOS/Linux for Live operations.

Install gda, the Godot CLI for AI agents, from PyPI onto your PATH:

uv tool install gda      # or: pipx install gda
gda --help

<details> <summary>Other ways to install (pip, from source)</summary>

Into an existing environment:

pip install gda

From source (for development or unreleased changes):

git clone https://github.com/aigengame/godot-agent.git
cd godot-agent
uv sync                  # create the environment + install dependencies
uv run gda --help

</details>

Quick start

Point gda at your Godot binary, then ask the engine its version — no project needed:

export GDA_GODOT="/path/to/Godot"   # or pass --godot to any command
gda info --json
# {"major":4,"minor":6,"patch":3,"status":"stable","string":"4.6.3-stable (official)",…}

With --json, stdout is clean JSON you can pipe; all engine and script diagnostics go to stderr:

gda info --json | jq .major   # → 4

Build a scene headlessly. Point gda at a Godot project (a directory with project.godot) once; relative paths then resolve inside it, and nodes are addressed by their path relative to the scene root:

export GDA_PROJECT="/path/to/your/godot-project"   # or pass --project to any command
gda scene create scenes/main.tscn --root-type Node2D --json
gda node add  scenes/main.tscn --type Sprite2D --name Hero --json
gda node set  scenes/main.tscn --node Hero --property position --value 10,20 --json
gda scene validate scenes/main.tscn --json
gda scene get scenes/main.tscn --json
# {"path":"scenes/main.tscn","root":{"name":"main","type":"Node2D","children":[{"name":"Hero",…}]}}

No project? gda still runs projectless on plain filesystem paths (relative to your current directory) — only res:// resolution needs a project. See Configuration.

Inspect and drive the running game with Live operations. These operations run the project's main scene, so point it at the one you just built via Godot's application/run/main_scene project setting (the editor's Application → Run → Main Scene), then start the daemon (macOS/Linux, Godot 4.6+):

gda project set application/run/main_scene --value res://scenes/main.tscn --json  # a Godot project setting key
gda daemon start             # start the daemon for $GDA_PROJECT (installs the in-game harness)
gda game tree --json         # the runtime scene tree, after _ready
gda perf monitors --json     # live engine counters: fps, memory, node count
gda daemon stop

(gda screen capture works live too, but needs a windowed session — start the daemon with gda daemon start --windowed.)

Choose your integration

gda provides one operation surface through three complementary access paths. Use the CLI, the Agent Skill, the MCP server, or a combination that fits your workflow. The underlying operations and structured results stay the same.

Not sure which path fits your workflow? See Godot MCP vs CLI vs Agent Skill.

| Access path | Best for | How | | --- | --- | --- | | CLI (gda) | humans, shell scripts, CI, and agents that can run commands | gda <group> <command> --json | | Agent Skill (gda skill) | coding agents that support Agent Skills and prefer a token-light CLI workflow | print or install the bundled guidance (below) | | MCP (gda-mcp) | MCP-compatible clients that discover and call tools | run the stdio server (below) |

Use the Agent Skill

gda ships a bundled Agent Skill that teaches an AI agent when and how to drive Godot from the CLI. Use it when your coding agent supports Agent Skills and you want reusable guidance without registering a server. The guidance stays aligned with your installed gda version. Print it, or install it into your agent's skills directory:

gda skill                                              # print SKILL.md (redirect it anywhere)
gda skill --install --provider claude --scope user     # resolve a known agent's skills dir
gda skill --install --dir ~/.claude/skills/gda         # …or give the directory yourself

The Agent Skill recipes list each agent's skills directory. Or fetch the same file straight from the repo — you still install gda, since the Agent Skill drives it:

curl --create-dirs -o ~/.claude/skills/gda/SKILL.md \
  https://raw.githubusercontent.com/aigengame/godot-agent/main/src/gda/skill/SKILL.md

Use the MCP server

gda-mcp is the bundled Godot MCP server for compatible clients. It implements the Model Context Protocol over stdio and is available through the [mcp] extra. Run it through uvx without a permanent install:

uvx --from "gda[mcp]" gda-mcp

The server resolves two pieces of context — which Godot project to drive and which Godot binary to run (MCP can't pass per-call flags):

• Project — set GDA_PROJECT. Without it, gda-mcp uses the workspace roots the client sends (the folder you have open) — but the MCP 2026-07-28 revision deprecates roots, so pinning GDA_PROJECT is the setup that keeps working. See Configuration.
• Engine — set GDA_GODOT to your Godot binary, e.g. "GDA_GODOT": "/path/to/Godot".

gda-mcp accepts both protocol eras — the pre-2026 MCP protocol and the 2026-07-28 revision — but not with the same project resolution: a pre-2026 client still sends roots, a client on the new revision does not, so it resolves from GDA_PROJECT or the server's cwd. Pin GDA_PROJECT before your client moves. On the new revision gda-mcp also marks tools/list cacheable (1-hour TTL).

Register with Coding Agents

<details> <summary>Claude Code</summary>

Project scope, .mcp.json at the repo root (auto-detects the project via roots):

{
  "mcpServers": {
    "gda-mcp": {
      "command": "uvx",
      "args": ["--from", "gda[mcp]", "gda-mcp"]
    }
  }
}

User scope (every project) — the CLI, which writes ~/.claude.json:

claude mcp add --scope user gda-mcp -- uvx --from "gda[mcp]" gda-mcp

</details> <details> <summary>Codex</summary>

Project scope, .codex/config.toml at the repo root (the project must be trusted):

[mcp_servers.gda-mcp]
command = "uvx"
args = ["--from", "gda[mcp]", "gda-mcp"]

[mcp_servers.gda-mcp.env]
GDA_PROJECT = "/absolute/path/to/your/godot/project"

User scope (available everywhere, but pinned to one project) — the same table in ~/.codex/config.toml, or add it with the CLI. Codex has no workspace variable, so GDA_PROJECT is an absolute