How to use Claude Code with Godot

Short answer: open a terminal in your Godot 4 project folder, run claude, and give it a short CLAUDE.md that names your Godot version and the commands to check its work. Claude Code edits your GDScript, then runs Godot with --headless to catch errors and run a test script. You playtest in the editor. A Godot MCP server is optional. Facts below come from Anthropic's and Godot's official docs and the MCP projects' own GitHub pages, checked Oct 25, 2026, and every Godot command was tested on Godot 4.7.2.

This guide is about the Claude Code setup and loop. If you want the full story of building a real game with an agent (we used Codex for an archery game), read Build a Godot game with AI coding agents.

First, the honest part: Claude Code is not free

Claude's pricing page marks Claude Code as not included in the Free plan. You need Pro ($20/mo billed monthly, or $17/mo on the annual plan at $200 up front), Max (from $100/mo), Team or Enterprise. Anthropic's quickstart also accepts a Claude Console account, which is pay as you go API credits. Checked Oct 25, 2026.

On a zero budget, you have options already in our library:

• OpenAI Codex, Cursor and GitHub Copilot have free tiers in our listings. Check each tool page for what we verified and when, since free limits change often.
• The free Claude chat can still explain GDScript and write a script you paste in yourself. You just do the file edits and test runs by hand.
• The same edit, check, test loop below works with any agent that can run terminal commands. Our Godot plus Codex guide shows it with Codex.

What you need

• Godot 4. The latest stable release was 4.7.2 (Aug 18, 2026) on Godot's GitHub releases when we checked. Use the standard build for GDScript.
• Claude Code, installed and signed in with a paid plan or Console account.
• Git, so you can undo any change the agent makes.
• Node.js 18 or newer, only if you add the optional Godot MCP server.

Setup, step by step

1. Install Godot and make it runnable from a terminal

Download Godot from godotengine.org/download. Claude Code runs Godot through the terminal, so it must be callable by name. Godot's command line tutorial recommends putting the editor binary on your PATH as godot:

• Linux: put the binary in /usr/local/bin and name it godot.
• Windows: scoop bucket add extras then scoop install godot.
• macOS: brew install godot. Without Homebrew, the binary lives at Godot.app/Contents/MacOS/Godot.

Check it works:

godot --version

Ours printed 4.7.2.stable.official.ed1daf0bf.

2. Create the project with Git metadata

In the Project Manager, create a new project in its own folder and choose the Git version control option. Godot's version control docs say this creates .gitignore and .gitattributes for you. For an existing project use Project, Version Control, Generate Version Control Metadata. The folder to ignore is .godot/, which is only a cache. Then run git init and make a first commit.

3. Install Claude Code and sign in

From Anthropic's quickstart. macOS, Linux or WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Homebrew (brew install --cask claude-code) and WinGet (winget install Anthropic.ClaudeCode) also work, but those two do not auto update. Open a new terminal and run claude --version. Then start it inside your project:

cd /path/to/your-godot-project
claude

Sign in when asked. Anthropic recommends Git for Windows on native Windows so Claude Code can use its Bash tool.

4. Add a CLAUDE.md made for Godot

Claude Code loads CLAUDE.md (or .claude/CLAUDE.md) at the start of every session, per Anthropic's memory docs. They suggest keeping it under 200 lines and concrete. Here is a starting file for a Godot project. Paste it at the project root and edit the version and folders:

# Godot project notes for Claude

- Engine: Godot 4.7.2, GDScript only (no C#). Use Godot 4 syntax:
  @export, @onready, await, CharacterBody2D. Never Godot 3 syntax.
- Godot binary: godot (on PATH). Project root is this folder.
- Layout: scenes/ for .tscn, scripts/ for .gd, assets/ for art and sound,
  tests/ for test scripts.
- Prefer editing .gd scripts. Only edit .tscn or .tres files when asked,
  and keep every ext_resource id and uid:// value intact.
- Commit .uid files. Move or delete a .uid file together with its script.
- Never edit or commit anything in .godot/ (it is a cache).

## Check every change
1. godot --headless --path . --import
2. godot --headless --path . --check-only --script res://scripts/FILE.gd
3. godot --headless --path . --script res://tests/smoke_test.gd
4. godot --headless --path . --quit-after 120
Read the output. Any line with SCRIPT ERROR or ERROR is a failure,
even when the exit code is 0.

## Ask first
- Before changing project.godot, input maps, autoloads or export presets.

You can also run /init to have Claude draft one from your project, then trim it. Run /context to confirm the file loaded.

The workflow loop

This is the loop that does the real work. Every command here was run on Godot 4.7.2 on Linux on Oct 25, 2026, using the flags in Godot's command line reference.

1. Prompt for one small change. For example: Create scripts/player.gd for a Node2D that moves with the arrow keys, with a move_step function I can test.
2. Import headless. godot --headless --path . --import starts the editor without a window, imports resources, then quits. It also creates the .uid files for new scripts.
3. Parse check the script. godot --headless --path . --check-only --script res://scripts/player.gd only parses for errors. A broken script prints SCRIPT ERROR: Parse Error with the file and line, and exits with code 1.
4. Run a test script. Godot can run any script that extends SceneTree with --script. The sample below loads your scene, calls a function and quits with 0 for pass or 1 for fail.
5. Run the game briefly. godot --headless --path . --quit-after 120 runs the main scene for 120 iterations and quits. Look for runtime errors in the output.
6. Fix and repeat. Claude reads the errors, fixes them and runs the checks again. Then press Play in the editor and judge how it feels.

Sample script under test:

extends Node2D

@export var speed := 200.0

func _process(delta: float) -> void:
	var dir := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
	move_step(dir, delta)

func move_step(dir: Vector2, delta: float) -> void:
	position += dir * speed * delta

Sample tests/smoke_test.gd:

extends SceneTree

# Run with: godot --headless --path . --script res://tests/smoke_test.gd
func _init() -> void:
	var scene: PackedScene = load("res://scenes/main.tscn")
	var main := scene.instantiate()
	var player = main.get_node("Player")
	player.move_step(Vector2.RIGHT, 1.0)
	var moved: bool = player.position.x > 0.0
	main.free()
	if moved:
		print("PASS: player moved right")
		quit(0)
	else:
		push_error("FAIL: player did not move")
		quit(1)

In our run it printed PASS: player moved right and exited 0. When we broke move_step on purpose it printed the FAIL error and exited 1.

Watch out: when we added a runtime error to _ready() and ran the game with --quit-after, Godot printed SCRIPT ERROR but still exited with code 0. That is why the sample CLAUDE.md tells Claude to read the output, not just the exit code. When you need more than a smoke test, GUT (Godot Unit Test) is a free testing add-on in our library.

Optional: add a Godot MCP server

MCP (Model Context Protocol) is a standard way to give an agent extra tools. You do not need it for the loop above. These are community projects, not made by the Godot Foundation or Anthropic.

Godot MCP (Coding-Solo) gives Claude tools to launch the editor, run the project, read debug output, create scenes, add nodes and manage UIDs. It needs Godot and Node.js 18 or newer. Its README gives this Claude Code command:

claude mcp add godot -- npx @coding-solo/godot-mcp

If it cannot find Godot, set GODOT_PATH:

claude mcp add godot -e GODOT_PATH=/path/to/godot -- npx @coding-solo/godot-mcp

Restart Claude Code and run /mcp to see it. In Anthropic's MCP docs, everything after -- is the command that starts the server, and --scope project writes the server to a shared .mcp.json instead of just your machine. We started the server with Godot 4.7.2 and it listed 14 tools, including run_project, get_debug_output and update_project_uids. We did not test it inside a signed in Claude Code session.

Godot AI connects Claude Code to a live editor so it can build scenes, edit nodes and wire signals. Per its README (v4.3.1 was the latest release on Oct 25, 2026): it needs Godot 4.7 or newer and uv. Install a release into addons/godot_ai/, enable it in Project, Project Settings, Plugins, then press Configure next to Claude Code in the Godot AI dock. Claude Code also needs a one time approval by running claude in the project. It records usage telemetry (no code or scene contents, per the README), which you can turn off with GODOT_AI_DISABLE_TELEMETRY=true. We did not install it for this guide.

Common pitfalls

• Hand editing .tscn and .tres files. Scenes and resources are plain text, but every node refers to resources by ext_resource ids and uid:// values. One wrong id and the scene will not open. Let Claude edit .gd files freely, and make scene changes in the editor (or through an MCP tool) unless you ask for a text edit. Save in the editor before Claude touches a scene file, and commit first.
• Losing .uid files. Since Godot 4.4, scripts and shaders get a .uid file next to them, like player.gd.uid. Godot's UID article says to commit them, never add *.uid to .gitignore, and move or delete them together with their script. Put that rule in CLAUDE.md so the agent does not "clean them up."
• Godot 3 code in a Godot 4 project. Models have seen a lot of old Godot 3 code. Godot 4.7.2 rejected each of these in our test with a clear parse error: yield (use await), export var (use @export), and onready var (use @onready). Node names changed too, like KinematicBody2D becoming CharacterBody2D (see the upgrading to Godot 4 docs). The --check-only step catches these fast.
• Trusting exit code 0. As tested above, runtime errors can print SCRIPT ERROR while Godot still exits 0. Read the output.
• Committing the .godot folder. It is a cache. Godot's generated .gitignore leaves it out.
• Huge prompts. Ask for one script or one bug fix at a time, check it, commit, repeat.

Sources (checked Oct 25, 2026)

• Claude Code quickstart, CLAUDE.md memory docs and MCP docs (Anthropic)
• Claude pricing (Anthropic)
• Godot command line tutorial and version control systems (Godot 4.7 docs)
• UID changes coming to Godot 4.4 (Godot blog)
• Upgrading from Godot 3 to Godot 4 (Godot docs)
• Godot releases on GitHub
• Coding-Solo/godot-mcp (community) and hi-godot/godot-ai (community)

Related

Want the whole game building story with an agent? Read Build a Godot game with AI coding agents. Using another engine with Claude Code? Follow How to use Claude Code with Unity or How to use Claude Code with Unreal Engine. Not sure which agent to pay for? Read Claude Code vs Codex vs Cursor for game dev.

Still picking an engine? See Godot vs Unity for beginners or Best game engines for beginners in 2026, or browse every coding and game logic tool.

FAQ

Is Claude Code free?

No. Claude's pricing page lists Claude Code as not included in the Free plan. It is included in Pro ($20/mo billed monthly, or $17/mo with the annual plan at $200 up front) and higher plans, or you can pay per use with a Claude Console (API) account. Checked on claude.com/pricing on Oct 25, 2026. Godot, Godot MCP and Godot AI are free.

Which Godot version should I use?

Godot 4. The latest stable release on Godot's GitHub was 4.7.2 (released Aug 18, 2026) when we checked on Oct 25, 2026, and that is the version we tested every command in this guide with. Tell Claude your exact version in CLAUDE.md, because Godot 3 and Godot 4 GDScript are different.

Do I need an MCP server for Godot?

No. Claude Code can edit your .gd files and run Godot from the terminal with --headless to catch errors and run tests. A community MCP server such as Godot MCP or Godot AI is optional and adds ready made tools for running the project, reading debug output or editing a live editor.

Is there an official Godot plugin for Claude Code?

We did not find one. Anthropic's official plugin marketplace had no Godot or GDScript plugin when we checked its catalog on Oct 25, 2026, and the Godot MCP servers we cover here are community projects, not made by the Godot Foundation or Anthropic.

Can Claude Code tell if my game is fun?

No. Headless runs and tests catch errors and broken logic. Only you, and your playtesters, can judge feel and fun, so press Play in the editor after every change that matters.

Does this work with C# in Godot?

This guide covers GDScript. C# projects need the .NET build of Godot and a separate build step, and the Godot AI README says its C# support is text only (it does not build .NET or report C# compiler errors). If you are new, start with GDScript.