GodotCli

<p align="center"><img src="docs/images/icon.png" width="96" alt="gdcli"></p> <h1 align="center">gdcli</h1> <p align="center"> <a href="https://www.npmjs.com/package/@spardanviro/gdcli"><img src="https://img.shields.io/npm/v/@spardanviro/gdcli?label=npm" alt="npm"></a> <a href="https://godotengine.org/asset-library/asset/5539"><img src="https://img.shields.io/badge/Godot%20Asset%20Library-gdcli%20bridge-478cbf" alt="Godot Asset Library"></a> <a href="https://github.com/spardanviro/GodotCli/actions/workflows/ci.yml"><img src="https://github.com/spardanviro/GodotCli/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <img src="https://img.shields.io/badge/Godot-4.3%20to%204.7-478cbf" alt="Godot 4.3 to 4.7"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0"></a> </p> <p align="center"><b>Let Claude Code, Codex, Cursor or any MCP agent build your Godot 4 game through the real editor.</b></p> <p align="center"><b>English</b> | <a href="README.zh-CN.md">简体中文</a></p>

---

gdcli connects a coding agent to a running Godot editor. You describe a game feature in plain words ("a 2D character that runs and jumps, with ground to stand on"). The agent builds it the way a person would: it creates nodes, sets properties, writes and attaches scripts, paints tiles and makes animations. Every step is on the editor's undo stack. Then it runs the game, presses keys and reads values in the running game to check that the character really jumps.

It works with the official Godot 4.3 to 4.7 builds, standard or .NET, on Windows, macOS and Linux. Nothing is compiled into the engine and no API key goes into Godot: the agent you already use does the thinking, and gdcli gives it hands and eyes in the editor.

You:   Make a 2D platformer character that moves left and right and jumps, with ground under it. Run it to check.

Agent: gd command scene_new --path res://main.tscn --root-type Node2D
       gd command node_create --type CharacterBody2D --name Player --properties '{"position": [200, 300]}'
       gd command node_create --type CollisionShape2D --parent Player --properties '{"shape": {"$new": "RectangleShape2D", ...}}'
       gd command fs_write_text --path res://player.gd --text-file /tmp/player.gd
       gd command node_attach_script --path Player --script res://player.gd
       gd command project_input_map_set --action jump --events '[{"key": "Space"}]' --yes
       gd command scene_save
       gd command editor_play
       gd command game_input --action jump --hold 0.1
       gd command game_node_get --path Main/Player --properties '["velocity", "position"]'   # it went up: done

Why

The usual way to let an AI write a Godot game is to have it edit .tscn and .gd files directly. That breaks in several ways:

• Scene files are easy to corrupt.
• Changes skip the editor's undo stack.
• The model never sees how the game actually behaves.
• Any code it writes may end up running inside your editor.

gdcli takes the other road: the agent works through the editor.

| | Editing files directly | With gdcli | |---|---|---| | Scenes and nodes | hand-written .tscn text, ids and paths by guesswork | 72 structured commands; the editor writes the files | | Undo | none | every change is a step of the editor's undo stack, Ctrl+Z works | | Seeing the result | at best, the text the game prints | read and set values in the running game, press inputs, take screenshots, breakpoints, locals | | Unsaved work in the editor | overwritten or ignored | the same scene the person sees, live | | Code running in the editor | whatever was written | @tool scripts, addons, autoloads, C# and eval wait for a person to click Allow | | Engine knowledge | whatever the model remembers | 17 skills with Godot 4 pitfalls, the API of your installed version, and the official manual |

What you can do with it

• Build scenes: nodes, properties, scripts, signals, groups, resources, animations (players, state machines, blend spaces, sprite frames), tile sets and tile maps with terrains, GridMap levels, themes, navigation meshes, import settings, ready-made particle effects and animations, collision shapes fitted to sprites and meshes.
• Change the project: project settings, input actions, moving and renaming files with references updated across scenes and scripts.
• Run and look inside: start the game from the editor and read its node tree and live values, play key, mouse and gamepad sequences, slow it down or speed it up, list what its UI shows, check several values at once, call methods, read errors and output with script stack traces, take screenshots, read the frame rate, memory, draw calls and orphan nodes.
• Debug: set breakpoints, pause, step, read the call stack and local variables of a stopped game.
• Without an editor: run a scene and get its errors with file and line, check scripts, run GUT or gdUnit4 tests, import, export, run a SceneTree script, look up any class of your Godot version, search the manual.
• From any agent: the same commands as a CLI (gd), as a Claude Code plugin, and as an MCP server for Codex, Cursor, VS Code, Gemini CLI and others.

The three parts

| Part | What it is | Required? | Install | |---|---|---|---| | Bridge (addons/gdcli) | An editor plugin in GDScript. Listens on 127.0.0.1, runs the commands, keeps the undo stack, asks a person when needed | Yes, for anything that touches the open editor | gd bridge install, the Godot Asset Library, or the zip on Releases | | gd command line | Finds the editor, sends commands, prints results; starts Godot itself for offline work; an MCP server | Yes | npm install -g @spardanviro/gdcli | | Claude plugin (godot@gdcli) | 17 skills (how to use gd, how Godot 4 is meant to be used) and 3 hooks (start-of-session hint, guards against writing project files behind the editor's back) | Optional, recommended with Claude; other agents get the same skills with gd skills install | the plugin marketplace, or upload the zip from Releases in the Claude app |

 agent / terminal                     Godot editor
┌──────────────┐   HTTP (loopback)   ┌──────────────────────────────┐
│ gd command … │ ──────────────────▶ │ bridge addons/gdcli          │──▶ scenes, undo stack, files
│ gd mcp       │   token + handshake │   asks a person when needed  │──▶ running game (debugger)
└──────┬───────┘                     └──────────────────────────────┘
       │ starts Godot directly (no editor)
       └──▶ gd run / check / test / import / export / api / docs

The bridge listens on the loopback address only. Its token is kept in your home folder (~/.gdcli), and every connection starts with an HMAC handshake that proves the other side holds the token. Details: docs/protocol.md (in Chinese).

Getting started

1. What you need

• Godot 4.3 or newer, any official build (standard or .NET). gdcli does not install Godot.
• Node.js 22 or newer, for the gd command line.
• For the agent part: Claude Code, or any MCP client (Codex, Cursor, VS Code, Gemini CLI, ...).

2. Install the command line and point it at Godot

npm install -g @spardanviro/gdcli
gd doctor

gd doctor says which Godot it found and what is missing. gd looks for Godot in this order:

1. --godot <path>
2. the GODOT_BIN environment variable
3. godot_bin in ~/.gdcli/config.json
4. godot, then godot4, on the PATH

On Windows, point it at the *_console.exe next to the editor, so that its output can be read.

gd and gdcli are the same command. If gd is taken by a shell alias (oh-my-zsh's git plugin makes it git diff), use gdcli or unalias gd.

3. Put the bridge into your project

Pick one of these:

a. With gd (recommended): it always installs the bridge of the same version as gd.

gd new my-game --renderer mobile   # a new project with the bridge already in it
                                   # (renderers: forward_plus, mobile, gl_compatibility)
# or, for a project you already have:
cd your-game
gd bridge install                  # copies addons/gdcli and enables it; --force to replace another version

b. From the Godot Asset Library, inside the editor:

1. Open your project in Godot and switch to the AssetLib tab at the top.
2. Search for gdcli, open "gdcli bridge", click Download, then Install. Keep addons/gdcli ticked.
3. Project > Project Settings > Plugins: tick Enable next to gdcli. This also adds its small GdcliGame autoload, which lets gd look into the running game.

The page is godotengine.org/asset-library/asset/5539. The Asset Library can be a version behind while a new release waits for review. gd warns when the bridge in a project differs from its own; gd bridge install --force brings them in line.

c. From a release zip: download gdcli-bridge-<version>.zip from Releases. Copy the addons/gdcli folder inside it into your project's addons/ folder, then enable it as in b.3.

4. Open the editor and check the connection

gd open          # starts the editor on the project (or open it yourself as usual)
gd status        # lists the editors gd can reach: you should see your project

On a machine without a display (a server, CI, WSL without a desktop), gd host start runs a headless editor instead, and gd host stop ends it.

5. Try a few commands yourself

gd command scene_new --path res://main.tscn --root-type Node2D --root-name Main
gd command node_create --type Sprite2D --name Logo --properties '{"position": [100, 50]}'
gd command scene_tree
gd command edit_undo                  # the same as Ctrl+Z in the editor
gd command edit_redo
gd command scene_save
gd run --headless --seconds 3         # runs the project for 3 seconds without an editor and reports its errors

You see each change appear in the editor as it happens. gd list lists every command the editor offers, with its arguments (--json gives the full schemas).

6. Hand it to an agent

Claude Code

Install the plugin (optional, but it is what teaches Claude how to use gd well):

claude plugin marketplace add spardanviro/GodotCli
claude plugin install godot@gdcli

Without the marketplace, use gdcli-claude-plugin-<version>.zip from Releases:

• Claude desktop app: Customize > Plugins > Add > Upload plugin, and pick the zip. The skills and hooks work in sessions that run on your machine (Cowork, Claude Code), where gd is installed. Chat on claude.ai loads only the skills and cannot reach your editor.
• Claude Code, for one session: claude --plugin-dir gdcli-claude-plugin-<version>.zip, or claude --plugin-url <the zip's release URL>.

See plugin/README.md for the details.

Then open Claude Code in the project folder and say what you want. For example:

Make a 2D platformer character that runs and jumps, with ground to stand on. Run it and check that jumping works.

The enemy walks through walls. Find out why and fix it.

Add a pause menu with Resume and Quit, opened with Escape, and check that the game really stops.

Translate the main menu into Chinese and Japanese, and add a language switch.

What happens:

• The skills load when they are needed: godot-cli for the commands, plus the topic or task one (tile maps, UI, shaders, multiplayer, troubleshooting, ...).
• Claude builds through gd command ..., and you watch the editor change. Ctrl+Z in the editor undoes its steps like your own