gda: Godot for AI agents
gda
The gda CLI, skill and MCP server: an agent builds a Godot project, validates scenes and drives the running game.
- 57 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Commands create and change scenes, scripts and project settings, and export writes build files.
- Operations run the project's own code: autoloads, scene scripts and the whole game.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/gdaDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Commands create and change scenes, scripts and project settings, and export writes build files.
- Operations run the project's own code: autoloads, scene scripts and the whole game.
This is third-party code. Review the repository files before installing.
What it does
gda is a Python console program that runs Godot without the editor and returns results as JSON. It has two modes. In headless mode an agent creates scenes, nodes, scripts, resources and shaders, compiles code, validates dependencies, boots a scene for a short check and exports a build. Live mode works through the `gda-daemon` daemon: it launches the game and lets the agent read the node tree, simulate input, capture frames, collect logs and errors and sample performance. The same operations are reachable three ways: the `gda` command directly, the bundled skill and the `gda-mcp` MCP server.
Who it is for. Game developers on Godot 4.6 or newer who hand scene building and project checks in CI to an agent.
Good fit when
- A scene with several nodes has to be built and validated without opening the editor.
- In CI a project is exported and scripts are compiled with a machine-readable report.
- The agent has to see the node tree of a running game and its errors.
- Key presses are simulated and a frame is saved to check behavior.
Not a fit when
- The project is on a Godot older than 4.6: the tool targets 4.6 and newer.
- The game is built on another engine, such as Unity.
- The project comes from an untrusted source: gda runs the project's own autoloads and scripts.
Example request
Create `scenes/main.tscn` with a Node2D root and a Hero sprite, validate it with `gda scene validate` and show the result.Limitations
Python 3.13 or newer and a Godot 4.6 or newer binary are required, with its path in `GDA_GODOT` or the `--godot` flag. The project is treated as trusted: autoloads and scene `_init` run during many operations, and `script run` executes the script in full. Frame capture works only in a windowed session, so the daemon starts with `--windowed`. The skill from the repository tracks the `main` branch, while `gda skill` prints the version matching the installed `gda`.
How to disable. Remove the package with `uv tool uninstall gda` and the skill by deleting the `gda` folder from the agent's skills directory. Delete the `gda-mcp` entry from the client config and stop a running daemon with `gda daemon stop`.
FAQ
How do I install gda for Claude Code?
Install the program with `uv tool install gda`, then the skill with `npx skills add aigengame/godot-agent --skill gda -g`. The skill drives the program itself, so install both.
How do I connect the gda MCP server?
Run `claude mcp add --scope user gda-mcp -- uvx --from "gda[mcp]" gda-mcp`. Set the project with `GDA_PROJECT` and the engine with `GDA_GODOT`.
Which to pick: CLI, skill or MCP?
All three paths give the same operations. The CLI suits shells and CI, the skill saves tokens for agents that support skills and MCP serves clients with tool discovery. A comparison is on the project site.
Is a Godot editor plugin required?
No. Headless operations run as one-shot processes without a plugin or daemon. For live mode the daemon injects a temporary in-game harness that export strips out.
How do I check that Godot is found?
Run `gda info --json`. The command prints the engine version, `4.6.3-stable` in the README example.
Discussion
No questions or reviews yet.
Related
CLI toolsA .NET addon lets an agent drive the Godot editor: scenes, nodes, scripts, viewport screenshots and queries in the RQL language
An MCP server and plugin for Godot 4.4+: the agent edits scenes and scripts in the editor, runs the game and reads errors
GodotMaker takes a game idea to a working 2D Godot prototype: agents plan, write code and tests, then verify the result.
A Godot addon and MCP server: the agent sees the scene tree, errors and screenshots of the running game and validates changes in the editor
An MCP server for the Godot engine: launch the editor, run projects and edit scenes from an agent
An MCP server for Godot 4 that runs inside the editor: the agent edits scenes, nodes and scripts, runs the project and reads the debugger, no Node.js
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| gda: Godot for AI agents (this card) | yes | 57 | ||
| Godot MCP | no | not required | 6,542 | launches the editor and edits scenes through MCP; gda works without the editor and adds a CLI, a skill and a live mode with a daemon |
| Godot AI | yes | API key | 3,414 | connects the agent to a running editor; gda needs neither the editor nor a plugin |
README in short
Installation runs through PyPI, a quick start with and without a project, three ways to connect an agent and a command reference. Collapsible blocks explain which project code runs and the structured output format with exit codes.