Godotwright

Godotwright

MCP server and CLI that makes Claude Code, Codex and any coding agent better at Godot 4.

Offline Godot 4.7 API, a project map, headless checks, an AAA review of GDScript, and 3D models built, viewed and checked from code.

Website · 3D model gallery · Quickstart · MCP setup · Benchmark · Roadmap

Coding agents learned Godot from years of Godot 3 tutorials. They write yield, export var and KinematicBody2D, invent methods, and wire signals to nodes that are not in the scene. Godotwright gives the agent the real Godot 4.7 API, a compact map of your project, real Godot checks and a fixed AAA review, as MCP tools and as a CLI.

Status: layer 1 (toolkit and MCP server) is done; see ROADMAP.md.

And it builds 3D models

A coding agent can also make, look at and check 3D models for Godot with no Blender: model identify says what a thing is (parts, sizes, pivots), model build makes a clean .glb from one of 44 ready-made kinds (vehicles, aircraft, ships, buildings, plants, terrain with lakes and rivers) or from your own JSON spec, model view shows it as text, and model lint scores it. It is set up to work with small, cheap models too: what we tested and learned.

Quickstart

npx -y godotwright review ~/games/my-game

You get a score from 0 to 100 for api, performance, quality and structure, and each finding as res://file.gd:12: error [rule] message with the Godot 4 fix. Then connect it to your agent.

Why Godotwright?

• No more Godot 3 code. The review flags Godot 3 syntax and names and gives the Godot 4 replacement.
• No invented API. Every class, method, property and signal is checked against the official Godot 4.7 class reference, bundled offline (1078 classes).
• Mistakes found before you press F5. Missing $Node paths, scene connections to methods that do not exist, unknown input actions and broken preload() paths.
• Cheap for the model. Compact, stable output, and a cheap profile that walks small models through small checked steps.
• Local and private. scan, api and review need no Godot install and no network.

Commands

godotwright scan [path]               # compact project map, cheap to read
godotwright scan [path] --detail full # node trees, signatures, line numbers
godotwright scan [path] --json        # the full map as JSON
godotwright check [path]              # run Godot headless, report errors as file:line
godotwright check [path] --run        # also run the main scene for 120 frames and show what it printed
godotwright check --scene res://scenes/Test.tscn   # run one scene instead: put print() in the code and read it back here
godotwright api Node2D.look_at        # offline Godot 4.7 API: classes, methods, signals
godotwright api --search "is on floor"
godotwright review [path]             # AAA review with a score per category
godotwright review [path] --detail full --min-score 90
godotwright model car.glb             # what is in a 3D model: nodes, triangles, textures, size
godotwright model lint car.glb        # model review with a score per category
godotwright model contract car.glb    # write a model.contract.json: node names, size, budget
godotwright model contract --archetype car   # the same, from what a car usually is (no model yet)
godotwright model lint car.glb --archetype car   # also check it is what it should be
godotwright model lint car.glb --contract model.contract.json
godotwright model brief "a tractor"    # one page before you build: kind to start from, parts, size, rules, order of work (for small models)
godotwright model identify "a tractor" # what it is: parts, size, variants, what to anticipate
godotwright model archetypes          # the family tree of things Godotwright knows
godotwright model kinds               # what `model build` can make, with parameters
godotwright model view car.glb       # see a model as text: front, side and top views, the parts, what does not touch
godotwright model recipes             # the ready-made recipes and the archetype each one is checked against
godotwright model recipes tractor     # print one recipe as a spec to edit
godotwright model build house -o house.glb --set floors=3 --set roof=hip
godotwright learn                     # what Godotwright learned on this machine

scan reads project.godot, scenes, resources and scripts without starting Godot. It lists scenes with their node trees, scripts with signals, functions and exports, autoloads, input actions and key settings, and warns about broken references (missing files, a missing main scene or autoload, bad preload() paths).

check needs Godot 4.7: --godot <path>, $GODOT, godot on your PATH, or a Godot 4 download it finds by itself (Program Files, Steam, Scoop, Downloads, Desktop). It imports the project, loads and instantiates every script and scene, and can run the main scene. Each problem comes back once, as res://path/file.gd:12: error: .... The exit code is 1 when there are errors.

api answers from the official Godot 4.7 class reference, bundled offline (1078 classes). It accepts Class, Class.member, Class.Enum.VALUE, @annotation or a global function, follows inheritance, and explains Godot 3 names (KinematicBody2D is CharacterBody2D in Godot 4). See data/README.md.

review needs no Godot install. It scores four categories from 0 to 100 and lists each finding as res://file.gd:12: error [rule] message:

The checks follow Godot's own rules (inheritance, scripts on more specific nodes, inherited scenes, built-in scripts, duck typing with has_method()), and are tuned on the official demo projects so they report real problems, not noise. The exit code is 1 when there are errors, or when the score is below --min-score.

model reads a .glb or .gltf file without Godot. model alone shows the node tree, triangle count, materials, textures (with an estimate of texture memory), size and lowest point. model lint scores four categories from 0 to 100:

Findings are grouped per node, and their severity follows how much of the surface is affected, so one stray triangle is an info and a flipped panel is an error. A model contract (model.contract.json) pins what a model must keep, so a renamed node or a hull that grows 3 cm wider is caught. model contract writes one from the model as it is now; review it, add a source to each size, and keep it next to the model. model contract --archetype car starts instead from what a thing usually is (its single parts by name, the middle of the typical size, a triangle budget), for a model that does not exist yet. With --contract, model lint reports contract-missing-node, contract-order, contract-extra-node, contract-size, contract-ground and contract-triangles. Sizes default to a 1% tolerance, or set tolerance in metres. The exit code is 1 when there are errors, or when the score is below --min-score.

model build makes a model from code, with no Blender or other tool: a clean .glb with UVs and tangents, named parts with sensible pivots, standing on y = 0, and the same bytes every time for the same parameters. The result goes straight through model lint, and --contract-out writes a model.contract.json for it. model kinds lists the kinds with their parameters, ranges and defaults; set them with --set name=value or --spec file.json. These are clean, parametric base models, built to be refined, not hand-sculpted art. Kinds today: house, the open-world kinds terrain (a heightmap tile from seeded noise whose neighbours continue it exactly, with an optional lake and an optional river carved into it) and sea (a subdivided water plane at y = 0 with a floor), plus recipes, which are ready-made specs in data/recipes/: car, tractor, helicopter, airliner, ship, tree, conifer, wind-turbine, shipping-container, truck, bus, motorcycle, bicycle, train, tank, light-aircraft, fighter, drone, boat, sailboat, piston-engine, jet-engine, barn, tower, church, windmill, apartment, bridge, road, railway-track, street-lamp, fence, power-pylon, palm, bush, grass, flower, crate, barrel, chair and table. Every recipe names its archetype, so model build checks it as it builds, and every recipe is tested to stay clean at the lowest and highest value of each parameter.

Small, cheap models can work blind: see docs/cheap-models.md for a test and what model view and the floating-part check do about it.

model identify says what a thing is before you build it, from its name in English or Dutch (typos, plurals and Dutch compounds like "vrachtauto" included) or from a description ("something with wheels and an engine"). It answers with the family it belongs to, the parts a model of it needs (and which move, about which axis, with the pivot where), a typical size range with its source and a confidence class, the variants (a car can be a sedan, a hatchback, a pickup), the Godot conventions (+Y up, the front faces +Z), what to anticipate (collision, LODs, lights) and the usual mistakes. A word that means two things (the Dutch "windmolen") is reported as ambiguous, and something it does not know gets the nearest family, marked generic, instead of a made-up answer. The library is data in data/archetypes/ and grows with pull requests. It also knows the pieces an open world is made of: terrain tiles, mountains, islands, coasts, seas, lakes, rivers, biomes and settlements, with their own rules (tiles that share border heights, y = 0 as sea level, collision from the same heights, levels of detail, instanced scatter, a floating origin for very large worlds).

model lint --archetype <what> (or "archetype": "vehicle.wheeled.car" in a spec, or any built-in kind) holds a model against what identify says that thing is, as a fifth category, archetype, worth a fifth of the score:

Anything else is built from a model spec: a JSON tree of named parts (box, cylinder, ellipsoid, lathe, loft, extrude, roof) with at, rotate, mirror, repeat, variables and arithmetic expressions ("$width / 2 - 0.1", never executed as code). model spec explains the format and prints a small car as an example; model build --spec car.json --set width=1.9 builds it. Every moving part is its own node with its pivot at its origin (a wheel at its hub), and a spec that goes wrong gets a message with its path (nodes[0].children[2].size[1]: unknown variable $x).

Review in GitHub Actions

Save this as .github/workflows/godot-review.yml in your game repository. It reviews the project on every push and pull request, failing if there are errors or the overall score is below 80. The static review needs only Node.js 22.12+ (Node 24 below), not a Godot install, model or API key.

name: Review Godot project
on: [push, pull_request]
permissions:
  contents: read
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 24
      - run: npx --yes github:laaielichter/godotwright#0dd9ce885df21fafefc09f8ddd6e92745d5ae303 review . --min-score 80

The toolkit is pinned to a revision; update that revision deliberately when you want a newer version. For a game in a subdirectory, set working-directory on the review step to the folder containing project.godot.

Mods and patches over a game

A mod or patch often uses scripts, scenes and models that live in the game, not in the mod's folder. Point Godotwright at the game so they count as present:

godotwright review mod/ --base game/                       # the game's source folder
godotwright review mod/ --base-files game/pck-manifest.json # files the shipped .pck holds

or put it in godotwright.json in the mod's root (paths relative to that root):

{ "base": ["../game"], "baseFiles": ["../manifests/pck-files.json"] }

The game's classes, autoloads, input map and scenes are then known, the mod's own files win where both have the same path, and only the mod's files are reviewed. A file list is text with one path per line, or JSON (strings, or objects with a path, resource or file key); exported names such as x.glb.import and x.gdc map back to their source.

Use with Claude Code, Codex and other coding agents (MCP)

godotwright mcp runs an MCP server over stdio with seven tools:

Pick a profile with --tier:

• cheap (default): short output, and server instructions that walk the model through small checked steps (scan, look up, review before saving, review after each edit).
• premium: full detail, all findings with fixes.

Claude Code

claude mcp add godotwright -- npx -y godotwright mcp --tier premium

Codex

codex mcp add godotwright -- npx -y godotwright mcp --tier premium

or in ~/.codex/config.toml:

[mcp_servers.godotwright]
command = "npx"
args = ["-y", "godotwright", "mcp", "--tier", "premium"]
startup_timeout_sec = 30 # the first npx run downloads the package

Run the agent from the Godot project folder (or pass --project <path>). CI connects both Claude Code and Codex to the server on every push.

Learning

Godotwright learns from every use, on your machine:

• Rules Godot keeps contradicting. After each check, it compares the review with what real Godot reported. When an error rule is contradicted 3 times here and never confirmed, its findings become warnings, marked as hints.
• False alarms. godotwright learn feedback wrong "<finding line>" (or the godot_feedback MCP tool) hides that finding in later reviews.
• API lookups. When a lookup finds nothing and the next one does, the next failed lookup of the same name says what it usually means.

Nothing leaves your machine unless you say yes. The learning file (godotwright learn shows where) holds counters, rule names, API names and message templates without names or paths; findings marked as wrong are stored as hashes.

godotwright learn          # status: what was learned, where the file is
godotwright learn off      # stop learning (or set GODOTWRIGHT_LEARN=0)
godotwright learn on
godotwright learn reset    # forget everything
godotwright learn preview  # the exact report sharing would send
godotwright learn share on # opt in: send anonymous counts once a day

Sharing helps every user: what many installs learn ships with later releases. It is off by default, sends no code, file names, paths or project names, and respects DO_NOT_TRACK. See PRIVACY.md. Set GODOTWRIGHT_HOME to keep the file somewhere else.

Godotwright also learns for free from public projects: every week the Learn workflow reviews the official Godot demos, and the same demos written for Godot 3, checks them with real Godot, and records which rules Godot confirmed or contradicted. That, plus what opted-in installs share, ships in data/learned.json: API hints for common typos, and rules Godot keeps contradicting. What your own machine saw wins: one confirmation by Godot keeps a rule an error.

For maintainers, godotwright collector serve accepts reports (checked again, stored without IP addresses), and godotwright collector aggregate <dir> --out data/learned.json sums them, keeping only what at least 3 installs reported. godotwright collector projects <dirs...> learns from public projects.

Benchmark

bench/ runs coding agents on fixed Godot tasks with and without Godotwright, and lets real Godot 4.7.2 judge the result with a behavior test per task. First round (168 runs, Claude Haiku, Sonnet and Opus 5.5, 12 tasks): every run passed, with and without Godotwright, so these tasks do not separate the setups on correctness. With Godotwright, all code came out fully statically typed (84 of 84 runs, against 71 of 84 without). Details and limits: bench/RESULTS.md.

How it compares

FAQ

Does it need Godot installed? No for scan, api and review. Only check runs Godot 4.7 headless.

Which agents does it work with? Any agent that speaks MCP over stdio. CI connects Claude Code and Codex on every push. The CLI works from any shell.

Does it send my code anywhere? No. See Learning and PRIVACY.md.

Older Godot 4 versions? Most findings apply to every Godot 4 version, but API lookups answer for 4.7.

Contributing

Wrong review findings and ideas for new rules are the most useful reports. See CONTRIBUTING.md.

Requirements

• Node.js 22.12 or newer
• Target engine: Godot 4.7.x

Development

npm ci
npm run check
node dist/cli.js --help

See AGENTS.md for project conventions.

License

MIT