Everything Godotwright does, in detail. For a quick start, see the README; for one-click installs, the install page.
- Commands
- Port Godot 3 scripts to Godot 4
- Shaders
- Review in GitHub Actions
- Export, check and run a build
- Scenarios and JUnit reports
- Mods and patches over a game
- Install in your coding agent (MCP)
- Tool sets and read-only mode
- Structured results
- Progress and cancel
- Protected paths
- Learning
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 test [path] # run the GUT or GdUnit4 tests headless; prints only what failed, with file:line
godotwright play --input "10 tap jump; 20 hold right 30" --watch Player.position # play input into a scene, see the values per frame
godotwright ci # one receipt: review, check, tests, scenarios and screenshot baselines (markdown, exit 1 on a failure)
godotwright ci --junit godotwright.xml # the same, plus JUnit XML for a CI test tab (tests, scenarios, review, check)
godotwright ci --annotations annotations.txt # GitHub Actions annotations for review findings and Godot diagnostics
godotwright scenario --save jump --input "10 tap jump" --expect "Hero.velocity.y == -400 @ 10" # run once, keep it as a test when it passes
godotwright scenario --list # the kept scenarios and their claims; `scenario` alone runs them all
godotwright doctor --symptom "falls through the floor" # what is wrong and in which order to fix it: review and Godot grouped by cause, with lessons
godotwright fix --write # apply the mechanical fixes for review findings (--check for the ones that need a look)
godotwright fix --stamp-uids --write # also give scenes, resources, scripts and shaders without a uid one, as Godot makes them
godotwright perf --scene res://level.tscn # frame times p50/p95/p99 against a budget, the slowest frames and their cause, vs the last run
godotwright leaks --scene res://chunk.tscn # load, run and free a scene 5 times: what grows per cycle, by class, script and scene, and where it is made
godotwright session start # load the main scene once, headless and paused; it stays up between commands
godotwright game step 120 --input "10 tap jump" --watch Hero.position --until "Hero.is_on_floor() == true" # play frames in the running game
godotwright game reload # put the scripts you edited into the running game; every node keeps its values
godotwright game ui --size 1280x720 --size 720x1280 # clipped labels, off-screen panels, overlapping buttons per window size
godotwright export # what the build will miss: excluded preloads, data files missing from include_filter
godotwright export run --preset Linux # export headless, check the pack against what the game loads, run it for 120 frames
godotwright export patch --preset Linux --against base.pck # a patch with only what changed, checked and run over the base
godotwright export pck game.pck # what a .pck (or a game .exe) holds, against the project; no Godot needed
godotwright deps unused # files nothing the game starts with reaches, biggest first; `deps why <file>` before deleting one
godotwright diff # what changed by meaning against git HEAD, and what it breaks elsewhere (`--ref main`, `--against old.tscn`)
godotwright impact # the scenes, tests and scenarios a change reaches, and the checks to run (or name the files)
godotwright collisions # physics layers and masks; `--between Player Enemy` says who detects whom and the mask to set
godotwright code diagnostics res://player.gd # Godot's own language server: warnings at the project's levels (also hover, definition, completion; --code for unsaved text)
godotwright shaders # the GPU pass: draw every shader (Compatibility renderer) for driver errors; errors at the line in the .gdshader
godotwright screenshot --scene res://hud.tscn --baseline # visual test: compares with .godotwright/baselines/, exit 1 when it changed
godotwright undo # take back the last Godotwright write (--steps n, --list)
godotwright dream # look back between sessions: proposals for lessons, hints, merges, with evidence (--transcripts, --apply 1,3)
godotwright screenshot --model car.glb --view front,side,top,iso # a PNG of a model from four sides (or of a scene); says how much is drawn
godotwright screenshot --scene res://hud.tscn --baseline hud # a named baseline: .godotwright/baselines/hud.png with its settings in hud.json
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 usages take_damage # every place a name or res:// path is used: code, scenes, connections, groups, settings
godotwright rename take_damage apply_damage --write # rename everywhere (code, scenes, connections, node paths); dry run without --write
godotwright rename res://a.tscn res://scenes/a.tscn --write # move a file with its .uid and .import, and every reference
godotwright project set display/window/size/viewport_width 1920 --write # change a setting; name and type checked against Godot 4.7
godotwright project input add jump --key Space --joy-button A --write # input map without hand-editing Object(InputEventKey,...)
godotwright project autoload add Game res://game.gd --write # checks the file is a Node and the name is free
godotwright scene add main.tscn . Music AudioStreamPlayer --write # add a node (or an instance: res://enemy.tscn); only that line changes
godotwright scene set main.tscn Timer wait_time 0.5 --write # property name and type checked; enums by name, resources as res:// files
godotwright scene connect main.tscn Timer timeout . _on_timer_timeout # warns when the method is missing or takes other arguments
godotwright scene editable main.tscn Enemy --write # [editable path="Enemy"]: this scene may change the instance's children (--off removes it)
godotwright resource set mat.tres roughness 0.8 --write # .tres: property name and type checked, uids kept, only that line changes
godotwright resource set level.tres data "[0, 1, 255]" # byte arrays as a plain list or base64:..., written as PackedByteArray
godotwright resource add-sub theme.tres StyleBoxFlat --id hover # then: resource set theme.tres bg_color "Color(0, 1, 0, 1)" --sub hover
godotwright resource diff car.glb # import options changed from the importer's defaults, and per-animation/mesh/node options
godotwright resource set music.ogg loop true --write # import option checked against the importer; reimported headless and verified
godotwright resource set beep.wav edit/loop_mode Forward --write # enum options by name
godotwright resource set car.glb settings/loop_mode Linear --sub animations/drive --write # per-animation loop
godotwright resource set car.glb generate/shadow_meshes Disable --sub meshes/car_body --write # per-mesh (named <scene>_<mesh>)
godotwright resource importer anims.glb animation_library --write # import a .glb as an AnimationLibrary, uid kept
godotwright migrate --write # port Godot 3 scripts and shaders to Godot 4 where that is mechanical; lists what is left
godotwright shader # review every shader against Godot 4.7's shader tables and compile it headless; file:line
godotwright api shader:spatial.fragment # the built-ins of a shader type and function; `api ALBEDO` says where one exists
godotwright review --sarif > review.sarif # for GitHub code scanning: findings inline on pull requests
godotwright review --github # GitHub Actions annotations, no code-scanning permission needed
godotwright review --only-new # in a fix loop: only what changed since the last review, the rest as one line each
godotwright review --from 4.5 --target 4.6 # moving between 4.x releases: what changes on the way (default: saved version -> 4.7)
godotwright check --compare-godot ~/Godot_v4.8-beta2 # the same check with a second Godot on a copy: only new and gone errors
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 model build house -o house.glb --collision trimesh # Godot adds collision shapes on import (-col / -convcol names)
godotwright model build tree -o tree.glb --no-textures # plain colours instead of texture maps: smaller, or for your own materials
godotwright model build terrain -o world/tile.glb --collision heightmap # terrain: a HeightMapShape3D and a ready tile scene
godotwright learn # what Godotwright learned on this machine
godotwright learn gaps # Godot errors it cannot predict yet: what to teach it next
godotwright lessons moving ship deck # lessons from real projects: symptom, cause, fix, how to test
godotwright lessons --error "<Godot message>" # the lessons that explain an error
godotwright lessons add --title "..." --fix "..." # keep a lesson learned here (scrubbed, never sent)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:
| Category | What it checks |
|---|---|
| api | Godot 3 code, unknown classes, functions, members and signals, wrong argument counts, input actions missing from the Input Map |
| performance | node lookups, load(), prints and physics calls in per-frame callbacks, empty callbacks, shadow-casting lights |
| quality | static typing coverage, long or deeply nested functions, signals never emitted, string-based signals, naming, TODOs |
| structure | broken references, scene connections to missing methods or signals, $Node paths missing from the scene, unknown groups, file naming |
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:
| Category | What it checks |
|---|---|
| geometry | triangles facing against their own normals (pink backfaces, wrong light), open edges on single-sided surfaces, edges shared by more than two triangles, triangles without area, negative scale, models that are almost but not quite left-right symmetric |
| materials | missing normals, UVs or tangents, UVs outside 0..1, very large or non-power-of-two textures, base colours real surfaces do not have (model/albedo, an info: a non-metal brighter than snow or darker than charcoal, or a dark "metal" that renders as a black mirror; a textured material is judged by the mean of its colour map) |
| performance | triangle budget (--max-triangles), texture memory budget (--max-texture-mb), many materials |
| rig | sibling nodes with the same name, unnamed nodes, a model that does not sit on y = 0, an empty file |
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. Materials look like what they are: brick, roof tiles, slate, wood, bark, leaves, grass, stone,
concrete, asphalt, sand and water get a seamless colour map and normal map at their real size, made by Godotwright
itself and stored in the .glb; glass, chrome, steel, paint, plastic and lamps that glow are plain PBR materials. 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, traffic-sign, guard-rail, delineator, fence, power-pylon, palm, bush, grass, flower, crate, barrel, chair, table, campfire, castle, crash-barrier, dragon, grandstand, horse, humanoid, race-kerb, rocket, rowing-boat, satellite and spaceship. 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:
| Rule | What it catches |
|---|---|
archetype/missing-part |
a car without wheels, a helicopter without a rotor (parts are recognised by node name in English or Dutch) |
archetype/part-count |
two wheels on a car, five on a bicycle |
archetype/pivot |
a wheel not turning about its hub, a door not pivoting on its hinge line, a turret not on its base |
archetype/wheel-axis |
a wheel lying the wrong way |
archetype/size |
a model about 10 times too big or small, which is nearly always a unit mistake (it only flags a difference of more than 3 times, since the ranges are typical, not exact) |
archetype/orientation |
a car that points sideways instead of along z |
archetype/optional-part |
the usual parts that are not there (info) |
Anything else is built from a model spec: a JSON tree of named parts (box, cylinder, ellipsoid,
lathe, loft, extrude, roof, tube) with at, rotate, mirror, repeat, variables and arithmetic
expressions ("$width / 2 - 0.1", never executed as code). Boxes and cylinders can have rounded edges (bevel),
ellipsoids an organic, lumpy outline (lumps) and flat fractures with sharp edges (cuts, for broken stone), a tube follows a path (frames, rails, pipes, branches), and a material
of your own can use any of the texture patterns in its own colour ("texture": "wood"): brick, roof_tile, roof_slate, wood, bark,
concrete, asphalt, plaster, leaf, grass, stone, sand, water, ground, granite, and for finishes grain (solid timber without plank joints), fabric, leather, painted, plastic, brushed and rust. 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).
Three checks without Godot, for the moment an agent thinks it is done.
godotwright diff # the files on disk against HEAD
godotwright diff --ref main # against another commit; --to compares two commits
godotwright diff res://player/ --json # only a folder, as JSON
godotwright diff res://b.tscn --against res://a.tscn # two files, no git neededdiff compares what the files mean. In a scene or resource: nodes added, removed, moved or renamed, each changed
property with resource ids resolved to paths (a changed sub-resource is opened up: shape.radius: 12 -> 16), groups,
children reordered, connections and what the file loads. In a script: functions, signals, variables, constants and
enums, and the functions whose code changed. Also project.godot (settings, input actions, autoloads), shader uniforms
and .import options. A file that changed only in ids, order or formatting is one line. Lines marked ! are what the
change breaks elsewhere: a scene connection to a function that is gone, an @export value still saved in a scene, a
material that sets a removed uniform, an input action or autoload code still asks for, callers of a function whose
argument count changed, files that name a deleted file. The exit code is 1 when there is one.
godotwright impact # everything that differs from git HEAD
godotwright impact res://player/gun.gd # or the files you nameimpact walks the project's file graph backwards from the changed files to every scene that loads them (nearest
first, with the chain in between; a scene that only loads the file later with load() is marked), says when a change
is global (an autoload, something an autoload loads, project.godot, a class_name many scripts use), names the
test files and saved scenarios that cover it, and ends with the checks to run for this change.
godotwright collisions # every physics node, the layers in use, and what can never work
godotwright collisions --between Player Enemy # who detects whom, why, and the mask value that fixes it
godotwright collisions --layers 1 3 # = value 5; --value 5 = layers 1, 3collisions reads bodies, areas, rays and TileSet physics layers from the scenes, with layer names from
project.godot. It reports a mask that scans a layer nothing is on, an area or ray with mask 0, an Area with
monitoring off whose body_entered is connected, a body or area without a collision shape and a CollisionShape
without a shape. Where code sets layers or makes shapes, it lists those lines and leaves the matching checks out.
godotwright leaks --scene res://chunk.tscn # 5 cycles of 60 frames: load, run, free; exit code 1 when anything grows
godotwright leaks --scene res://world.tscn --keep --input "10 press load_chunk; 40 press unload_chunk" # keep the scene, replay input per cycle
godotwright leaks --cycles 10 --budget-objects 2 --json # a budget per cycle for CI, JSON for scriptsleaks (MCP: godot_leaks) runs a scene headless in cycles. By default every cycle loads the scene, runs it for
--cycle-frames frames and frees it; one frame later, when queued frees have run, it snapshots the live objects.
--keep keeps the scene running and snapshots every --cycle-frames frames instead. The input timeline (--input, as
play takes it) replays inside every cycle, so a game that streams chunks on input can be cycled too. The first
--warmup cycles (default 1) are not counted: caches and first-time loads fill them.
For the counted cycles it reports the growth per cycle (a least-squares slope, counted as a leak only when it grows in at least half of the cycles and never drops):
- orphan nodes (
Node.get_orphan_node_ids(), children counted with their top node), grouped by class, script and scene, with the parent they were removed from, the code that makes them (MeshInstance3D.new(), a class_name or preload alias,instantiate()of a scene, an exportedPackedSceneproperty, a scene that instances it) and theremove_child()that dropped them; - nodes left in the tree after the scene was freed (added to the root or an autoload), with where they hang;
- objects that are not nodes (objects minus nodes): Godot is run with
--verbose, so at exit it names the classes still alive (Object x5) and the resources still in use, with the code that makes them; growth that is not on that list was freed only at exit, so a static var, autoload or cache holds it, and the growing containers are named; - loaded resources, static memory, and the change since the last run of the same scene with the same mode, cycle length and input (
.godot/godotwright/leaks/).
The verdict is LEAKING (exit code 1, an error result over MCP) when objects or orphan nodes grow more than the budget
per cycle (--budget-objects, --budget-orphans, default 0). With --keep, nodes that pile up in the tree are shown
but not counted, since spawning can be the design. Each kind of leak names its lesson. Not visible to it: objects
GDScript cannot list one by one (they show only as counts and at exit by class), and the call stack that made a node
(Godot does not record it; the creation sites come from the project's code). A site proven by its remove_child()
or found in the scene's own scripts is shown as made at; a class matched elsewhere in the project, or one of several
remove_child() calls, is shown as maybe made at / maybe removed at.
check names leaks too: when the run step ends with ObjectDB instances were leaked at exit or resources still in use,
it runs once more with --verbose and lists the classes (MeshInstance3D x1, Object x1) or resource paths.
godotwright resource (MCP: godot_resource_edit) edits text resources and import settings without the editor.
Nothing is written without --write (write: true); the dry run shows the changed lines. Several changes go in one
call with resource apply <file> '<JSON list>' (MCP: the ops list), so there is one write and one reimport.
.tres(and the sub_resources of a.tscn):set,unset,add-sub,remove-sub,get. Property names and types come from the Godot 4.7 reference and the script's exports; enums by name, resources asres://files (anext_resourcewith its uid is added) orSubResource("id"), packed arrays as a plain list ([0, 1, 255]) or, for bytes,base64:.... Only the changed lines are touched: the uid lines are never rewritten. A sub_resource is moved before the first one that uses it (Godot cannot load a forward reference), anext_resourcethe edit left unused is removed, and a sub_resource still in use cannot be removed. Writes report the review errors before and after. An open editor keeps its cached copy, so reload the resource there.- Import settings: give the asset (
beep.wav) or its.import.get(one option: type, default and choices),diff(what differs from the defaults),set,unset(back to the default). Option names are checked against what Godot already wrote for the asset and the importer's class reference, because Godot drops unknown options without a word. Per-sub-resource options of the scene importer go through--sub(sub):animations/<name>(settings/loop_mode,save_to_file/*, slices),meshes/<scene>_<mesh>(generate/shadow_meshes,generate/lightmap_uv,generate/lods),materials/<name>(use_external/enabled,use_external/path) andnodes/PATH:<node>(mesh_instance/cast_shadow,generate/physics, ...).<scene>is the glTF scene's name, or the file name when the scene has none or its name starts with "Scene";.,:,@,/,"and%become_. Node paths start at the glTF root nodes (below the single root only for a file written withGODOT_single_root). Animation and material names are checked against the glTF; a mesh or node name that is not found only warns.importerswitches betweensceneandanimation_library,textureandimage, or tokeep, keeping the uid. - Verified reimport: after a
.importwrite Godotwright runsgodot --headless --importand reads the result back:changed(Godot kept every value and the imported output changed, by itsdest_md5; it also changes for a per-item option Godot ignores, so it does not prove the option took effect),same(kept, but the output is identical),dropped(Godot did not keep a value) orfailed, with the import errors for that asset.--no-reimportskips it; without Godot the file is written and the result says it was not reimported.resource reimport <asset>only runs the import. The journal entry is stored after the import, sogodotwright undostill works after Godot rewrote the.import; undo restores the settings, and the next import rebuilds the output.
godotwright migrate # shows every change it would make, and what still needs a hand
godotwright migrate --write # applies them
godotwright review # what is still wrong, with line numbersmigrate rewrites the mechanical part of a port: export, onready and tool become annotations (with @export_range,
@export_enum, @export_file, @export_flags, @export_color_no_alpha, @export_exp_easing and typed arrays where the hint is clear),
network keywords become @rpc(...) annotations, simple setget becomes Godot 4 property syntax (set = ..., get = ...),
renamed classes, functions, properties and constants get their Godot 4 names (only when the old name no longer exists in Godot 4 and
is not defined in the script), yield(x, "sig") becomes await x.sig, connect("sig", target, "method", [binds]) becomes
sig.connect(target.method.bind(...)), emit_signal and funcref become signals and callables, update() becomes
queue_redraw() in CanvasItem scripts, and members that moved (OS.get_ticks_msec()) move to their new class. Strings,
comments and node paths are left alone. What it cannot do safely it lists with the line: a setget it cannot convert,
move_and_slide(velocity), master/mastersync, yield() without arguments, update() in scripts with a path base,
export hints it does not know. Scenes and project settings are not touched; Godot's own --convert-3to4 does those.
Commit first; a second run makes no further changes.
migrate also ports .gdshader and .gdshaderinc files: the names in Godot's own shader rename table (hint_albedo and
hint_color to source_color, hint_black_albedo to source_color, hint_default_black, WORLD_MATRIX to
MODEL_MATRIX, CAMERA_MATRIX to INV_VIEW_MATRIX, INV_CAMERA_MATRIX to VIEW_MATRIX, NORMALMAP to NORMAL_MAP,
TRANSMISSION to BACKLIGHT, ALPHA_SCISSOR to ALPHA_SCISSOR_THRESHOLD, hint_aniso to hint_anisotropy,
depth_draw_alpha_prepass to depth_prepass_alpha, ...), also inside #define lines, and SCREEN_TEXTURE,
DEPTH_TEXTURE and NORMAL_ROUGHNESS_TEXTURE get the sampler uniform Godot's own error suggests
(uniform sampler2D SCREEN_TEXTURE : hint_screen_texture, filter_linear_mipmap;). It lists CLEARCOAT_GLOSS (now
CLEARCOAT_ROUGHNESS, which is 1.0 - gloss), a particle shader's vertex() (now start() and process()) and COLOR
written in a spatial fragment() as work by hand. Shaders stored inside scenes are not rewritten.
godotwright review --only-newEvery review remembers its findings in .godot/godotwright/review-last.json (Godot projects ignore .godot/ in git). With
--only-new (MCP: only_new: true) the next review prints the findings that are new since then in full, the ones you
already saw as one short line each (file:line [rule]), and how many are fixed. A finding keeps its identity when its
line moves. An agent fixing a long list reads the list once instead of after every edit.
godotwright shader # every shader: static review, then a headless compile when Godot is found
godotwright shader --file res://fx/water.gdshader # one shader (an include also compiles the shaders that use it)
godotwright shader --no-compile # static review only, no Godot needed
godotwright shader --compile --json # CI: fail when Godot is missing, JSON out, exit 1 on an error
godotwright shader --gpu # also draw them on the GPU (Compatibility renderer, xvfb-run on Linux)shader (MCP: godot_shader) checks every .gdshader, every .gdshaderinc and every Shader resource stored in a scene
or resource (reported as res://level.tscn::Shader_id:line, with the line in the scene file) in two ways:
-
A static review against Godot 4.7's own tables. The built-ins of each shader type and processor function, which of them are read-only, the stage functions and the render modes come from
servers/rendering/shader_types.cppof the 4.7.2 source, bundled in the API data; an integration test compiles every entry with Godot 4.7.2. The findings are ordinary review rules, sogodot_review, its score, SARIF, the CI receipt, the post-edit hook andgodot_feedbacksee them too:Rule What it finds api/shader-renamedGodot 3 names from Godot's rename table ( hint_color,WORLD_MATRIX,NORMALMAP,depth_draw_alpha_prepass, ...),CLEARCOAT_GLOSS,EXTRA_MATRIX, and a particle shader'svertex()api/shader-removed-builtinSCREEN_TEXTURE,DEPTH_TEXTUREandNORMAL_ROUGHNESS_TEXTURE, which are sampler uniforms with a hint nowapi/shader-builtin-misplacedA built-in of another shader type ( ALBEDOin acanvas_itemshader), another processor function (COLORin a spatiallight()), or a processor built-in used in your own function (UVin a helper);discardinvertex(); stage functions such astexture_sdf()where Godot does not offer themapi/shader-read-only-builtinA read-only built-in written, such as COLORin a spatialfragment()(writeALBEDO) orVERTEXinfragment();COLORinvertex()is fineapi/shader-render-modeA render or stencil mode the shader type does not have, with the nearest names api/shader-typeA missing or misspelled shader_typestructure/shader-missing-includeAn #includewhose file does not exist (Godot only saysUnknown character #35: '#')quality/shader-color-no-source-colorA colour uniform ( vec3/vec4named like a colour, or written straight intoALBEDO,EMISSION,COLORorFOG) or albedo texture withoutsource_colorin a 3D, sky, fog or particle shader; Forward+ and Mobile then use the sRGB value as linear. Quiet on the Compatibility renderer, which does not convertperformance/shader-discarddiscardin an opaque spatial shader: Godot can no longer use its shared depth-only material for the mesh's depth prepass and shadows (info)performance/shader-screen-readA spatial shader that reads the screen, depth or normal-roughness texture: it draws in the transparent pass and, without depth_prepass_alpha, has no depth prepass and casts no shadow; Godot copies the screen or depth buffer for it (info)performance/shader-texture-in-loopTexture reads in a loop with more than 16 reads per pixel, or an open-ended count (info) quality/shader-reads-own-depthA shader that reads the depth texture while it writes depth in the alpha prepass Names a shader declares itself (uniforms, locals, structs,
#defines, and those of the files it includes) are never taken for built-ins, and when an include is missing the built-in rules stay quiet rather than guess. -
A headless compile by real Godot. Under
--headlessGodot's dummy renderer still runs the full shader compiler, but only when a shader is used:load()alone does not compile it,get_rid()does. So no display, GPU,xvfbor rendered frame is needed, and it runs in CI. Unsaved code (code+file) and Shaders stored in scenes are compiled from their code with their own path, so relative#includes resolve as in the game. Godot's errors come back asres://file:line: error [godot] message: the line Godot names (at: (null) (:4)), or the line in the include. Godot's code echo and the follow-upShader compilation failed.are left out, a two-line message is kept whole, and a Godot error on a line the review already reports is shown once.compile: false(CLI--no-compile) skips this step; without Godot it is skipped with a note unless--compilerequires it. -
With
--gpu(MCP:gpu: true), the GPU pass. Headless, no GPU driver ever sees the code, so what only a driver rejects is not found there: a uniform block bigger than the GPU allows (uniform float big[200000]), a sampler array indexed by a variable, a GLSL compile or link error. The GPU pass (the same asgodotwright shaders) draws every shader on the Compatibility renderer for a few frames, xvfb-run on Linux without a display, and adds those as[gpu]lines; the language errors it finds again at the same line are shown once. It draws the files on disk, not unsaved code, and parses fog shaders only (they need Forward+). On a test project with broken spatial, canvas_item, particles, sky and fog shaders, a broken include and a broken shader in a scene, the headless compile found every language error at the same line as the GPU pass in under a second; the GPU pass took about 6 s and added the two driver errors.
godot_check compiles every .gdshader headless too, also those no scene uses, and reports them as
res://file.gdshader:line; shaders: true (CLI check --shaders) adds the GPU pass over the whole project, and an
error both find is reported once.
godot_fix renames the Godot 3 names and adds the missing texture uniforms (both safe). godot_api answers shader
questions: ALBEDO gives every shader type and function that has it and whether it can be written there,
shader:canvas_item.fragment lists a function's built-ins (shader:spatial adds the render modes), and hint_albedo
gives its Godot 4 name.
Agents copy scenes, invent uids and hand-write .tscn files. Godot then loads the wrong file, warns on every load,
fails to load a scene, or drops an edit the next time someone saves in the editor. godotwright review (and the
post-edit hook) finds these from the files alone, in milliseconds; godotwright fix repairs the ones that can be
repaired mechanically, through the undo journal. Each rule was reproduced with Godot 4.7.2.
| Rule | What Godot does | Fix |
|---|---|---|
structure/duplicate-uid |
Two files claim one uid (a copied .tscn, or a script or asset copied with its .uid or .import file): "UID duplicate detected" on every import, and a reference by uid can load the other file |
safe: the file most references name with that uid keeps it (a base project's file always does); the others get a new uid, and references that name them by path follow. When references name the uid alone (run/main_scene, preload("uid://...")), the file Godot loads for it now (its .godot/uid_cache.bin) keeps it, so they keep loading the same file; with no cache that choice is check |
structure/invalid-uid |
A header, .uid or .import uid that is not uid:// plus lowercase letters and digits is ignored: the file has no uid |
safe: a new valid uid |
structure/unknown-uid |
An ext_resource uid no file has: "invalid UID ... using text path instead" on every load |
safe: the uid of the file the path names, or no uid=; a script, shader, scene or resource that lost its uid (a .uid file not committed) gets back the uid its references use |
structure/uid-path-mismatch |
The uid names another file than the path: Godot silently loads the uid's file | check: the uid of the path's file |
structure/missing-resource-id |
ExtResource("x") or SubResource("x") with no section of that id, or a sub_resource used above its definition: "Parse Error", the file does not load |
by hand; the message lists the ids that exist |
structure/duplicate-resource-id |
Two ext_resources or sub_resources with one id: Godot keeps one (the last ext_resource, the first sub_resource) | by hand |
structure/section-order |
An ext_resource after a sub_resource or node, or a sub_resource after a node or [resource]: "Parse Error" |
by hand |
structure/unused-resource (info) |
A section nothing uses: still loaded with the file | safe: removed |
structure/locked-instance-edit |
An override of a node inside an instanced scene, a node added below one, or a connection to one, without [editable path=...] for every instance on the way: applied on load, dropped on the next editor save |
check: adds [editable path=...] |
godotwright review # the findings, with file:line
godotwright fix # dry run: every change, labelled safe or check, with a count (0 means nothing was done)
godotwright fix --check --write # apply them; godotwright undo takes them back
godotwright fix --stamp-uids --write # also give every scene, resource, script and shader without a uid a new oneNew uids are made the way Godot's ResourceUID.create_id() and id_to_text() make them (a random 63-bit id in base 34,
digits a-y and 0-8), and Godot registers them as written. When a uid in a .uid or .import file changes, the
file it belongs to is touched so that Godot's file cache reads it again. godotwright check (MCP: godot_check) tags
Godot's own uid warnings with the rule that predicts them ([structure/duplicate-uid], [structure/unknown-uid]).
godotwright scene (MCP: godot_scene_edit) refuses to set a property on, add a node under or connect to a node inside an
instance that is not editable, unless you pass --make-editable (MCP: make_editable); scene editable (MCP: op
set_editable) adds or removes the entry by itself. Files in a base project or only in a .pck list are context: their
uids count, their own problems are not reported.
godotwright screenshot --baseline (MCP: godot_screenshot with baseline) renders the scene or model and compares
it with the last approved picture. baseline is one of:
- nothing (CLI) or
"auto"(MCP):.godotwright/baselines/<scene or model>-<hash>@<size>_<views>.png, named after what was rendered, its size and views; - a
.pngpath inside the project (or the model's folder); - a name (
hud):.godotwright/baselines/hud.pngand ahud.jsonnext to it with how it was taken (scene or model, views, size, frames, threshold and tolerance when given, Godot version, graphics driver). Later runs reuse those settings, so--baseline hudalone compares like for like;godotwright cicompares every named baseline.
The first run saves the picture as the baseline; commit it (Godot does not import .godotwright/). Later runs compare
pixel by pixel and say what changed in text:
baseline hud CHANGED: 0.94% of pixels changed (544 px; threshold 0.5%, tolerance 3); largest change at (112, 64) size 64x32, mean shift 88.4
areas: (117,70)-(170,95) 544 px moved (12,0)
where: centre 8.5%
baseline: /game/.godotwright/baselines/hud.png
new: /game/.godot/godotwright/diff/hud.actual.png
diff: /game/.godot/godotwright/diff/hud-diff.png (changed pixels in red)
Next: look at the diff; if the change is intended, run again with --update-baseline; if not, fix it and screenshot again.
- A pixel counts as changed when its colour moves by more than
--tolerance(0 to 255, luma-weighted, default 3). The picture counts as changed when more than--thresholdpercent of the pixels changed (default 0.5); a change within the threshold is still named, with its diff. A named baseline keeps a threshold and tolerance you give it. - Areas of change are listed biggest first, with
moved (dx,dy)when a shift of up to 16 px explains one both ways (something moved, not removed). A brightness shift of 3 levels or more is named (darker,brighter). - A blank picture is named on every screenshot, baseline or not: black, white, fully transparent, the background colour only, or one colour over at least 99.9% of the picture.
- The diff picture is the baseline faded to grey with the changed pixels in red, in
.godot/godotwright/(Godot does not import it and version control usually ignores it). --update-baseline(MCP:update_baseline: true) replaces the baseline;--baseline-dirkeeps named baselines elsewhere (over MCPbaseline_dirmust be inside the project). A change beyond the threshold, or a size that differs, gives exit code 1 (MCP: an error result with the diff and the new picture); unchanged returns text only.- Runs are deterministic: a fixed frame rate (
--fixed-fps 60), fixed random seeds (also for particles), the Compatibility renderer and a fixed window size. Two runs on one machine give the same bytes. Another GPU driver or Mesa version can shade edges a few levels differently, so make baselines on the machine (or CI image) that compares them; a changed compare of a named baseline says when the driver differs. Compatibility does not draw Forward+-only effects (SDFGI, volumetric fog), so those are not covered.
A scenario can take pictures during its input run and compare each with its baseline:
{
"input": "0 hold right 20",
"frames": 40,
"expect": ["Hero.position.x >= 60 @ 30"],
"screenshots": ["walk-start @ 0", { "name": "walk-end", "frame": 30, "tolerance": 8, "threshold": 1 }],
"size": "640x360"
}The picture of frame N is taken after that frame's physics and process step has been drawn, the same frame the
expectations read. Missing baselines are made on the first run; godotwright scenario --update replaces them. A run
with screenshots draws with the Compatibility renderer (xvfb-run on Linux without a display) instead of --headless.
godotwright ci adds a visual step: every baseline made with godotwright screenshot is rendered again and compared
(baselines kept elsewhere with --baseline-dir need the same --baseline-dir on ci, or the Action's baseline-dir input),
and the screenshot steps of the scenarios are listed with it (the scenarios step judges only what the game did). In CI
a missing baseline fails instead of being made, since a baseline made on the runner would be thrown away. The GitHub
Action installs xvfb when it is missing and uploads .godot/godotwright/diff/*.png (diffs and new captures) as the
godotwright-visual-diff artifact.
godotwright review # a project saved by 4.5 or 4.6 also gets what changes on the way to 4.7
godotwright review --from 4.6 # the same after the project was re-saved in 4.7 (the saved version is then 4.7)
godotwright review --from 4.5 --target 4.6 # only the changes up to 4.6
godotwright api InputEvent.device # each member shows what changed in 4.6 and 4.7, and gone names say when they went
godotwright check --compare-godot /path/to/godot-4.8-beta # or set GODOT_NEXT and pass --compare-godot alonedata/api-changes.json holds the changes from the official 4.6 and 4.7 upgrade guides that matter to GDScript and
scenes, each checked by running the same project in Godot 4.6.2 and 4.7.2 (or, for rendering, marked as taken from the
guide). Review turns them into rules (MCP: godot_review with from and target):
| Rule | Since | When |
|---|---|---|
api/packed-element-write |
4.7 | line.points[0] = v, poly.polygon[i] += v, points[0].x = v: the element write to an engine property is lost (error) |
quality/packed-setter-skipped |
4.7 | the same on a script variable with a setter: the array changes but set() no longer runs |
api/override-missing-return |
4.7 | an override without a return type (also of _get, _set, _get_configuration_warnings) that never returns a value: the script no longer loads |
api/image-unit-bool |
4.7 | true/false as width_unit/height_unit of RichTextLabel.add_image()/update_image(): a parse error, although the guide calls it compatible |
api/input-device-zero |
4.7 | .device == 0 on a key or mouse event (they are 16 and 32 now); on a plain InputEvent only as an upgrade note |
api/upgrade-world-boundary-jolt |
4.7 | a WorldBoundaryShape3D with d != 0 under Jolt: the sign flipped |
api/upgrade-area-mask |
4.7 | a 2D/3D audio player at the default area_mask while an area uses audio_bus_override (default 1 -> 0) |
api/upgrade-mesh-skeleton |
4.6 | a MeshInstance3D under a Skeleton3D without a skeleton line (default .. -> empty) |
quality/upgrade-note |
4.6, 4.7 | glow and volumetric fog that will look different (4.6), soft bodies under Jolt (4.7) |
The first five are always on: they describe how Godot 4.7 behaves, whatever version the project came from. The
upgrade ones appear only while the project moves: from the version in config/features (or --from) up to --target.
After the project is saved in 4.7 its version reads 4.7, so pass --from to keep seeing them. A target older than 4.7
leaves the 4.7 rules out. Gone members say since when (removed after Godot 4.6), from data/api-removed.json, which now
also covers the 4.6 to 4.7 removals.
godotwright fix (MCP: godot_fix) does the mechanical part, with --from as above: a packed element write becomes
copy, write, assign back (safe on an engine property, check on a script setter, which now runs again), a bool image
unit becomes IMAGE_UNIT_PERCENT/IMAGE_UNIT_PIXEL, and area_mask = 1 or skeleton = NodePath("..") is added to the
node (the value before the upgrade). The Jolt plane is left to you: flipping d twice would undo it.
For a release review has no rules for yet (a 4.8 beta), --compare-godot <binary> (MCP: godot_check with
compare_godot, or next for $GODOT_NEXT) runs the same check with both binaries and prints only what differs:
new in 4.8.beta2 and gone in 4.8.beta2, matched by file, line and message (numbers left out). The second binary runs
on a temporary copy of the project without .godot/ and .git/, so a newer engine never re-imports or rewrites your
files; the copy is removed afterwards. The exit code is 1 only for new errors, so it fits a CI job that tries the next
release.
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 80The 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.
To see the findings inline on pull requests, upload the review as SARIF to GitHub
code scanning (this needs security-events: write and the repository's code
scanning enabled):
permissions:
contents: read
security-events: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 24
- run: npx --yes godotwright review . --sarif > godotwright.sarif || true
- uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: godotwright.sarifRun this from the repository root and point review at the project folder
(for example review game --sarif): SARIF paths are relative to the repository
root, so code scanning can place the findings on the right files.
"Works in the editor, broken in the build" is found before anyone ships. godotwright export (MCP godot_export)
checks the presets without exporting. godotwright export run (MCP godot_export_run) exports for real, headless,
and checks the result instead of trusting it:
godotwright export run --preset Linux # --export-pack: needs no export templates
godotwright export run --preset Linux --mode release # --export-release: needs the templates of this exact Godot version
godotwright export run --preset 0 --frames 0 --json # by number, no smoke run, JSON for scripts- Before Godot runs: the preset must exist (a missing one lists the presets there are),
export_presets.cfgmust not start with a byte order mark (Godot 4.7.2 then reads no presets at all and says "Invalid export preset name"), and a release or debug build needs export templates for the exact version (4.7.2.stable); a pack needs none. - The export:
--import, then--export-pack,--export-releaseor--export-debuginto.godot/godotwright/export/<preset>/(the preset's ownexport_pathis left alone;--outpicks another file and its folder is made). Godot's exit code is used, and its multi-line errors are kept whole. The file must also be there and big enough: Godot can fail and still leave a file behind, which is reported as not to ship. - The contents: the pack is read without Godot (PCK format 2 to 4; format 4 is what 4.7.2 writes; a pack inside
an executable is found from its end; an encrypted directory is detected and its file count shown). Every file the
game loads from where it starts (main scene, autoloads, settings, then
ext_resource,preloadandloadwith a literal path) must be in it, after mapping exported names back (x.gdcandx.gd.remaptox.gd,x.png.importtox.png); a missing one is an error with the chain that loads it and the preset's reason (anexclude_filter, or a plain file thatinclude_filterdoes not name). Editor-only scripts (extending anEditor*class, which export templates do not have) and test code shipped are warnings, one per folder, with theexclude_filterto add. The static audit's predictions for the preset are checked against the real pack. - The smoke run: the exported game runs headless for
--frames(default 120) at the project's physics rate, in an empty folder so no project files mix in: the exported binary itself when it runs on this machine, else Godot with--main-pack(which also opens an executable with the pack inside). Runtime errors come with their call chain, as ingodotwright check, and what the game printed is shown.
The exit code is 1 on any error, so it works as a CI step. In CI, the pack mode needs only the Godot binary:
godotwright ci --export-preset Linux adds an export row to the receipt (pack, contents, smoke run), and the GitHub
Action takes it as the input export-preset.
godotwright export pck game.pck (MCP: godot_export with pck) reads a pack you already have and compares it with
the project, and godotwright export smoke game.pck runs one.
godotwright export patch (MCP: godot_export_run with mode patch) makes a patch .pck with only what changed, and
lists every file it carries (~ changed, + new, - removed):
godotwright export patch --preset Linux --against base.pck # Godot's --export-patch, checked
godotwright export patch --preset Linux --manifest pck-manifest.json # no base .pck here: cut from a full export- Against base packs (
--against, in load order, or the preset'spatches): Godot's own--export-patch. The patch is then checked against a fresh full export of the project: no file in it may be the same as in the base, and every file that changed (or is new) must be in it; a file the base has and the project lost should be removed. Nothing changed is not an error: no patch is written. - Against a list of the base game's files (
--manifest, orbaseFilesingodotwright.json), for a mod over a shipped game whose multi-gigabyte .pck is not here: JSON withresource,md5andbytesper file (a .pck manifest), a list of paths, or one path per line. Godotwright exports the full pack and keeps the files whose md5 differs from the list or that are new. With paths only, a listed file cannot be told apart from an unchanged copy, and the report says so. - The smoke run writes one pack that holds the base with the patch over it (a later file replaces an earlier one, a
removal takes it out, as Godot loads them) and runs that with
--main-pack. With only a list, it runs the project's full export and says so; a patch with delta-encoded files (patch_delta_encoding) is not run.
A scenario is a regression test kept in the project, in .godotwright/scenarios/<name>.json. It is a godot_play
run written down: a scene, an input timeline and claims about what the game did. godotwright ci runs every
scenario headless and deterministically, with no editor.
{
"name": "jump",
"input": "10 tap jump",
"frames": 90,
"signals": ["Hero.jumped", "Hero.landed"],
"expect": ["Hero.velocity.y == -400 @ 10", "Hero.jumped == 1 @ 10", "Hero.landed == 1", "Hero.is_on_floor() == true"]
}expect: at least one claim,<Node.property> <==|!=|>=|<=|>|<> <value> [@ frame]. Without a frame, the claim is checked on the last frame. A claim on a recorded signal ("Hero.landed >= 1 @ 60") counts how often the signal fired up to that frame.- Optional:
scene(default: the main scene),watch(more values to sample),frames(default 120, or one past the last frame a claim names),until(stop at the first frame a condition holds; the scenario fails when it never does), andsignals(the signals to record). Files written beforeuntilandsignalsexisted still work.
To keep a proof, an agent calls godot_scenario with op save and the same arguments as the godot_play run.
On the command line, use godotwright scenario --save <name> with --scene, --input, --watch, --frames,
--until, --signal and --expect. Godotwright runs the scenario once more and writes the file only when every
claim holds, so a scenario that never passed cannot get into the project. An existing file is only replaced with
overwrite (--overwrite), and godot_undo takes a save back. op list (--list) shows the scenarios and their
claims. op run (no flag) runs all of them, or the one you name (else every name that contains it). A passing
scenario takes one line. A failing one shows every failing claim with the value the game had and the frame.
JUnit XML. godotwright ci --junit <file>, godotwright test --junit <file> and
godotwright scenario --junit <file> also write the results as JUnit XML, the test report format of GitLab
(artifacts:reports:junit), Jenkins, Azure DevOps and the JUnit report actions on GitHub. The printed output does
not change. In the file:
- Each scenario is a suite with one test case per claim. A game error or a run that stopped early is an
<error>case namedrun. - GUT and GdUnit4 suites are kept exactly as the framework wrote them. A test run that left no report (a crash or a
timeout) is an
<error>case, so it cannot pass silently. ciaddsreviewandcheckas test cases of the suitegodotwright.
The GitHub Action takes junit: godotwright.xml and passes the path on as the output junit:
- uses: laaielichter/godotwright@<version>
id: godotwright
with:
junit: godotwright.xml
- uses: actions/upload-artifact@v4
if: always()
with:
name: godot-tests
path: ${{ steps.godotwright.outputs.junit }}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 holdsor 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.
One step for each client. Every setup and one-click button is on the install page.
| Client | How |
|---|---|
| Claude Code | Plugin with the MCP server, hooks, eleven skills and eight subagents: /plugin install godotwright --marketplace laaielichter/Godotwright |
| Claude Desktop | Download godotwright.mcpb and open it (from release 0.2.0) |
| Cursor | Add to Cursor (one click) |
| VS Code (Copilot) | Install in VS Code (one click) |
| Codex | codex mcp add godotwright -- npx -y godotwright mcp --tier premium |
| Gemini CLI | gemini extensions install https://github.com/laaielichter/Godotwright |
| Windsurf, Zed, others | JSON for your client |
The Claude Code plugin puts Godotwright in Claude's loop, so it does not depend on Claude remembering a tool:
- Hooks: every Godot file Claude edits is reviewed right after the edit and its errors go straight back to
Claude; Godot errors in a command's output come with the lessons that explain them; before Claude stops, review
errors left in files it changed are named once; and a session in a Godot project starts with a few lines about it.
GODOTWRIGHT_HOOKS=0turns them off. Any agent can use them:godotwright hook <event>reads Claude Code's hook JSON on stdin (pre-edit,post-edit,post-bash,stop,session-start).pre-editrefuses edits into protected paths. - Settings (
userConfig): the Godot project, the Godot program, protected paths, tool sets and read-only, all optional. They reach the server asGODOTWRIGHT_PROJECT,GODOT,GODOTWRIGHT_PROTECT,GODOTWRIGHT_TOOLSandGODOTWRIGHT_READ_ONLY, and the hooks asCLAUDE_PLUGIN_OPTION_<KEY>. - Skills Claude uses on its own: the Godot workflow, and
debug,perf,vehicles,world,modelandpatch(changes to a shipped game with preflight, receipts and rollback). - Skills you start:
/godotwright:review(review the project and fix what it finds),/godotwright:port(port Godot 3 code to Godot 4) and/godotwright:learn(teach Godotwright what the session learned). - Seven subagents:
godot-reviewer(verified review),godot-debugger(root cause),godot-migrator(Godot 3 to 4),godot-performance(measurements),godot-shader-specialist(shaders and materials),godot-model-builder(3D assets) andgodot-test-engineer(unit, gameplay and visual regressions). Delegate a focused task; edits require an implementation request. Missing engine and renderer checks are reported, not counted as passes. On Claude Code older than 2.1.275, run/plugin marketplace add laaielichter/Godotwrightand then/plugin install godotwright@godotwright. Only the MCP server, without the skills:
claude mcp add godotwright -- npx -y godotwright mcp --tier premiumCodex can also read it from ~/.codex/config.toml:
[mcp_servers.godotwright]
command = "npx"
args = ["-y", "godotwright", "mcp", "--tier", "premium"]
startup_timeout_sec = 30 # the first npx run downloads the packageRun the agent from the Godot project folder, or pass --project <path> (or set GODOTWRIGHT_PROJECT).
Pick a profile with --tier:
premium: full detail, all findings with fixes. Use it with large models.cheap(the default): short output, and server instructions that walk a small model through checked steps (scan, look up, review before saving, review after each edit).
CI connects both Claude Code and Codex to the server on every push.
| Tool | What it does |
|---|---|
godot_doctor |
Start here when something is broken: the review and Godot grouped by cause, most urgent first, each with its lesson and fix, then numbered next steps |
godot_scan |
Map the project: scenes and node trees, scripts, signals, autoloads, input map |
godot_api |
Exact Godot 4.7 lookup: signatures, inheritance, Godot 3 names |
godot_api_search |
Search the Godot 4.7 class reference |
godot_review |
AAA review with scores; also reviews unsaved code (code + file), or only what changed (only_new); from/target for upgrades between 4.x releases |
godot_checklist |
Every AAA rule with its fix |
godot_feedback |
Mark a review finding as wrong or right, or say whether a lesson helped, so Godotwright learns from it |
godot_lessons |
Lessons from real Godot projects (symptom, cause, fix, test) by words, Godot error, rule or topic; gaps lists what it cannot predict yet |
godot_lesson_add |
Keep a lesson learned here, scrubbed of names, paths and code; it comes back when the same error does |
godot_dream |
Look back between sessions (learning file, journal, optionally session transcripts) and propose draft lessons, project hints, merges, retirements and fixes for contradictions, each with its evidence; nothing changes until apply |
godot_usages |
Every place a name or res:// path is used: code, scenes, connections, groups, settings |
godot_diff |
A diff by meaning against git: scene nodes added, removed, moved or renamed, properties with resource ids resolved, connections, script functions, signals and exports, settings and shader uniforms; marks what the change breaks elsewhere (a connection to a removed function, a saved @export value, callers with the wrong argument count) |
godot_impact |
What a change reaches: every scene that loads the changed files (default: what differs from git), whether it is global (autoload, project.godot), the tests and saved scenarios that cover it, and the checks to run |
godot_collisions |
Physics layers and masks from the scenes: every body, area and ray by name and bit value, who detects whom between two of them with the exact mask to set, and what can never work (a mask on an empty layer, monitoring off, no shape) |
godot_rename |
Rename a name or move a file everywhere at once, keeping connections, node paths and .uid files right |
godot_project_edit |
Change settings, input actions and autoloads in project.godot, touching only that entry |
godot_scene_edit |
Add or remove nodes, set properties, connect signals, attach scripts and make instances editable in a .tscn; refuses a change Godot would drop on the next editor save |
godot_resource_edit |
Edit a .tres (properties, sub_resources, uids kept) and import settings (.import options, per-animation, mesh, material and node options, importer switch); a written .import is reimported headless and checked |
godot_migrate |
Rewrite Godot 3 GDScript and shaders to Godot 4 where that is mechanical, and list what is left |
godot_shader |
Review every shader against Godot 4.7's shader tables and compile it with Godot headless; gpu: true also draws it for GPU driver errors; errors as file:line |
godot_code |
Godot's own GDScript language server, kept warm: diagnostics at the project's warning levels, hover (inferred types and signatures), definition and completion, also for unsaved code |
godot_deps |
The project as a graph of files from where the game starts: unused files with their size (paths the code builds count), why a file is used, what a scene loads with it, scene loops Godot cannot load |
godot_undo |
Undo the last Godotwright writes (edits, renames with their moves, migrations, fixes, model builds), newest first; a file changed by hand since is left alone |
godot_fix |
Apply the mechanical fixes for review findings, each labelled safe or check, uid repairs across files included; shows them first, then reviews the changed files again |
godot_check |
Run Godot headless (load every script and scene, compile every shader) and report errors as file:line, runtime errors with their call chain; shaders: true also draws every shader; compare_godot diffs against a second Godot |
godot_test |
Run GUT or GdUnit4 tests headless; only what failed, with file:line |
godot_play |
Run a scene with an input timeline and return the values you watch per frame; until a condition, signals with their frame, summary per value, expect claims |
godot_export |
Before an export: files the presets leave out although the game loads them, plain data files missing from include_filter, paths built under excluded folders; with pck, what an exported pack holds |
godot_export_run |
Export headless (pack, release, debug or patch), check the file and the pack's contents against what the game loads, then run the build for some frames with runtime errors and call chains |
godot_scenario |
Keep a passing godot_play run as a regression test in the project (save runs it once more first), list them, run one or all with every failing claim, its value and frame |
godot_session |
Load a scene once and keep the game running between calls, headless and paused, until you stop it |
godot_game |
Look at and drive that running game: live tree, get and set values, call, eval, step frames with input until a condition holds, 3D layout (floating, buried, scale), rays, UI issues per window size, hot reload of edited scripts (state kept), new errors with their call chain |
godot_perf |
Measure a scene's frame times: p50/p95/p99 against a budget, the slowest frames and what changed on them, the change since the last run |
godot_leaks |
Load, run and free a scene in cycles and report what grows per cycle: orphan nodes by class, script and scene with where they were made and removed, nodes left behind, objects that are not nodes, what Godot held at exit; fails over a budget |
godot_screenshot |
Render a scene or a .glb to a PNG and say how much is drawn and whether it is blank; with baseline, a visual test: unchanged as text only, or the percent changed, the areas of change and moves, and a diff picture |
godot_model_brief |
One page before you build, for small models: the kind to start from, parts, size, rules and the order of tools |
godot_model_identify |
What a thing is: parts, pivots, typical size with its source, variants (English or Dutch) |
godot_model_spec |
The model spec format, an example and the ready-made kinds |
godot_model_library |
Search over a thousand ready-made base recipes (furniture, street, storage, nature, buildings, vehicles, props) in English or Dutch; build one by id or take its spec as the start of your own |
godot_model_build |
Build a clean .glb from a kind or a spec (inside the project), and lint it |
godot_model_lint |
Score a .glb; with archetype also check it is what it should be |
godot_model_view |
See a .glb as text: front, side and top views, parts with sizes, parts that do not touch |
godot_model_inspect |
What is in a .glb: nodes, triangles, textures, size |
Every tool definition goes into the agent's context on every turn. All 43 cost about 88,000 characters (about
22,000 tokens); the core set about 24,000. Load only what the work needs, or run lean (below):
godotwright mcp --tools core # or GODOTWRIGHT_TOOLS=core
godotwright mcp --tools core,run,godot_session,godot_game
godotwright mcp --read-only # or GODOTWRIGHT_READ_ONLY=1
godotwright mcp --lean # two tools instead of all: see Lean mode| Set | Tools | Size of the tool list |
|---|---|---|
core |
scan, api, api_search, review, check, code, doctor, fix, usages, lessons, feedback, undo, checklist | 13 tools, ~23,900 characters |
edit |
rename, scene_edit, project_edit, resource_edit, migrate, shader, lesson_add, dream | 8 tools, ~18,600 |
verify |
diff, impact, collisions | 3 tools, ~6,500 |
run |
test, play, scenario, perf, leaks, screenshot | 6 tools, ~16,500 |
game |
session, game | 2 tools, ~5,400 |
export |
export, export_run, deps | 3 tools, ~5,500 |
model |
model_brief, model_identify, model_spec, model_library, model_build, model_view, model_lint, model_inspect | 8 tools, ~11,800 |
all (default) |
everything | 43 tools, ~88,100 |
Sets and single tool names mix (core,godot_play; the godot_ prefix may be left out). An unknown name stops the
server with the valid names. The server instructions name only the tools that are enabled, so a small model is never
told to call a tool that is not there. The default stays all on both tiers, so nothing changes for existing setups.
--read-only means "does not change the project's files":
- left out:
godot_undo,godot_model_buildandgodot_export_run, which always write; - kept, but
write: trueis refused, so they show their dry run:godot_fix,godot_rename,godot_scene_edit,godot_project_edit,godot_resource_edit,godot_migrate; - refused:
godot_scenarioopsave,godot_gameopsset,callandeval,godot_dreamwithapply, andgodot_screenshotwithmodelorbaseline(they write the picture into the project); - kept as they are: the review, API and lessons tools (they write only counters to the local learning file in your
home folder, which
GODOTWRIGHT_LEARN=0turns off), and the tools that run Godot.
Read-only does not make an untrusted project safe: godot_check, godot_test, godot_play, godot_perf,
godot_leaks, godot_screenshot, godot_session and godot_doctor (when Godot is installed) run the project's own
scripts, and Godot rewrites its cache in .godot/. For a project you do not trust, also leave out the sets that run
Godot (--tools core still has godot_check and godot_doctor; pass godot: false to the doctor) or do not install
Godot where the agent runs.
godotwright mcp --lean # or GODOTWRIGHT_LEAN=1
godotwright mcp --lean --tools core,verify --read-onlyA full tool list is paid on every turn, whether a tool is called or not, and some clients stop at 40 tools. With
--lean the server offers two:
godotruns any tool by name:{"tool": "review", "args": {"files": ["res://player.gd"]}}(the name with or withoutgodot_). Its description holds the catalogue: every enabled tool with one line on what it is for.godot_helpgives a tool's description and parameters ({"tool": "review"}), finds a tool by words ({"query": "collision layers"}), or lists them all.
| Tools in the list | Size of the tool list | |
|---|---|---|
| full (default) | 43 | ~88,100 characters (~22,000 tokens) |
--tools core |
13 | ~23,900 |
--lean |
2 | ~3,500 (~900 tokens): 96% less |
--lean --tools core |
2 | ~2,100 |
The tools, their checks, results (structured results included), tool sets and read-only refusals are the same. A call
with a wrong, missing or unknown argument is answered with what is wrong and the tool's parameters, so one bad call
corrects itself; unknown arguments are an error here (the full server drops them), because the model has not seen the
parameters. The server instructions say how to call, and keep naming the tools as godot_....
What you give up: the model reads a tool's parameters with one extra call the first time it uses it, and a client
that asks for permission per tool sees one tool, godot, for everything (use --read-only or --tools to limit
what it can do). Use it with clients that have a tool limit, with small context windows, and next to other MCP
servers. Clients that load tool definitions on demand by themselves gain less.
godot_review, godot_check, godot_doctor and godot_test declare an outputSchema and return
structuredContent next to the same text as before (clients that read only the text see no change). One compact shape:
{
"ok": false, "errors": 1, "warnings": 3, "truncated": 0,
"findings": [
{ "file": "res://player.gd", "line": 4, "severity": "error", "rule": "api/wrong-arguments", "message": "..." }
]
}Each finding has severity and message, and when known file (res://), line, rule, source (where it was
found: script, scene, import, run, review, godot, test) and count (how often Godot printed it, or how many places a
doctor problem has). findings is capped like the text (15 on the cheap tier, 200 on premium) and truncated says how
many were left out. Per tool:
godot_review:project,overallandcategories(score per category); the findings are those the text lists (samefilesfocus; infos left out on the cheap tier with brief detail). Withonly_newthe text shows the delta and the JSON the current findings.godot_check:godotVersion,scripts,scenes,shaders,frames(when it ran the game). Withcompare_godotthe findings are only what the second Godot reports.godot_doctor:godot(ran, not installed, skipped, failed),overall,next(the numbered steps); each problem is one finding at its first place. It is never an error result.godot_test:framework,tests,passed,failed,skipped; failing tests come first with ruletest/failureortest/error, then what Godot printed.
An error result (isError) still carries structuredContent when the tool got that far (a check with errors, failing
tests, a review of a file that is not in the project). MCP clients skip the schema check on error results; the schema
holds there too. When Godot is missing there is only the text.
Every tool call runs Godot inside a run context. When the client sends a progressToken, Godotwright sends
notifications/progress for each Godot run: the phase when it starts (import: started, load: started,
play: started, export: started, shader compile: started, session: loading res://main.tscn) and, at most about
once a second, what Godot reports: import steps with their percentage, load: 60/212 files for a check, and
play: frame 120/600 for play, perf, leaks and scenarios. progress counts up by one; there is no total.
SDK clients that pass resetTimeoutOnProgress keep a long godot_check or godot_test alive this way.
When the client cancels the call (notifications/cancelled), Godotwright stops the Godot process and every process it
started (its process group on Linux and macOS, taskkill /T on Windows), waits for it to exit, and does not start the
next step of that call. godot_session op start stops the game it was starting. Godot processes still running when
the server exits are stopped too. The CLI is unchanged: there Godot stays in the terminal's process group, so Ctrl+C
reaches it.
Some folders must stay byte-identical: an installed game, a base project a mod is laid over. Name them in a
godotwright.json under "protect":
{ "protect": ["installed-code", "baseline-authoring"] }Entries start at the folder of that godotwright.json; res://... means the same (the folder is the project), and
../baseline-authoring works from a project's own file. Godotwright reads the protect lists of every
godotwright.json in and above the folder written to, in and above the folder the agent runs in and the server's
default project, and in the direct subfolders of the folder the agent runs in, so the list can live outside what it
protects (changing a file inside a protected folder to add it would break the byte-equality it guards).
GODOTWRIGHT_PROTECT (paths separated by commas or the OS path separator; relative to the working folder) and the
Claude Code plugin's "Protected paths" setting add more.
What is refused:
- Godotwright's own writes, in every client (the CLI too):
godot_scene_edit,godot_project_edit,godot_resource_edit,godot_fix,godot_migrate,godot_rename(both ends of a move),godot_model_build(outandcontract_out),godot_export_run(out),godot_screenshot(a model's picture,out, and a baseline it would make or update; comparing one still works),godot_scenarioopsaveand new baselines of its screenshot steps, andgodot_undo(checked for every file before any is put back). The tool returns an error that names the path and thegodotwright.jsonthat protects it; dry runs still work. A call that touches several files stops at the first protected one; what it wrote before stays in the journal, sogodot_undocan revert it. - Claude Code's own edits, with the plugin: a
PreToolUsehook onWrite,Edit,MultiEditandNotebookEditdenies the call with the reason (permissionDecision: "deny"). It looks only when aprotectlist or setting is in reach, so other edits cost nothing extra. - The list itself: a
godotwright.jsonthat holds a non-emptyprotectlist is guarded the same way, so an agent cannot edit the list away before its next write; change it by hand. A symlink is followed to its target, also when the target does not exist yet.
Not covered: Bash commands are not parsed (cp, sed -i, > or git checkout into a protected folder go
through), and neither are other MCP servers. Claude Code's own permission rules ("deny": ["Edit(./installed-code/**)"]
in .claude/settings.json) can add a second line of defence. Godot's cache folder .godot/
inside a protected project is not protected: godot_check and the other tools that run Godot update it, as Godot
itself does when it opens the project. Like every hook, the hook fails open: when Godotwright cannot run or the input
is not what it expects, it allows the edit and says nothing.
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 thegodot_feedbackMCP 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.
- Rules that cry wolf. A rule whose findings were marked wrong 5 times here, and wrong at least three times as often as right, is reported one level lower (an error becomes a warning, a warning an info). One local "right" keeps it where it was, whatever other installs said.
- Lessons.
godot_lessons(orgodotwright lessons) answers from lessons learned in real projects: what went wrong, why in Godot terms, the fix and how to test it.godot_checkprints the lesson under a Godot error it explains, andgodot_reviewnames the lesson behind a finding. Say whether a lesson helped (godot_feedbackwithlesson): lessons that help rank higher, ones marked wrong more often than right stop showing up unasked. - Lessons you teach it. When a fix took more than one try, keep it with
godot_lesson_add(orgodotwright lessons add), with the Godot message it explains. Names of the project, paths, links, e-mail addresses, codes, keys and source code are replaced before it is stored; a lesson that is mostly names is refused. The next time Godot prints that message, the check shows your fix. - What to teach next.
godotwright learn gaps(orgodot_lessonswithgaps: true) lists the Godot errors the review did not predict and no lesson explains yet, most frequent first. A gap that many installs share is the next review rule.
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; lessons you add are stored scrubbed and are never sent.
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 daySharing 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.
Lessons from real builds also become rules. data/lessons.json holds 272 anonymised lessons from large Godot 4
projects (helicopters and ships landing on moving decks, open worlds tens of kilometres wide, cockpits and head-up
displays, streaming and levels of detail, VFX and shaders, runtime-loaded models, audio, UI, installers for shipped
games, headless test rigs and frame-time measurement): no code, no names, no paths, and a test runs every one through
the same scrubber that local lessons go through. The ones a review can catch are rules, such as api/infer-variant
on loop variables over untyped arrays, api/override-signature, api/void-return-value,
api/freed-check-order, api/parse-into-typed,
api/duplicate-declaration, api/coroutine-without-await, api/timer-start-outside-tree,
api/multimesh-format-after-count, performance/runtime-gltf-mipmaps, performance/subviewport-always,
quality/shader-reads-own-depth, quality/time-modulo-window, quality/worker-task-not-waited and
model/opaque-glass.
LESSONS.md tells the story behind them, and LESSONS-ROADS.md does the same for
a road network generator (links, bridges, viaducts over rail and motorways, roundabouts, guard rails). Lessons you keep locally can be proposed for everyone:
godotwright lessons export prints them as entries for data/lessons.json; nothing is sent.
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.
godotwright dream [path] (MCP: godot_dream) looks back at what Godotwright learned and did in a project, between
sessions, and proposes what to keep. It is deterministic (no model, no network) and changes nothing until you apply.
It reads:
- the local learning file: Godot errors the review did not predict (
missedByReview), failed API lookups and what came next, lesson counts (shown, helped, wrong), local lessons, rule counts, and findings marked wrong or right; - the project's journal (
.godot/godotwright/journal/): which writes were undone, by tool and file kind (only those; the journal keeps no names for this); - with
--transcripts(MCPtranscripts: true) only: this project's Claude Code transcripts (~/.claude/projects/<project folder>/*.jsonl, also for the repository root above the project;$CLAUDE_CONFIG_DIRmoves it) and Codex transcripts (~/.codex/sessions, matched by the folder they ran in;$CODEX_HOMEmoves it). The newest 40 changed within--sinceare read, each from its last 4 MB. Kept from them: calls to Godotwright tools by name, Godot errors in tool output as message templates (no names, paths or numbers; a template with anything personal left is dropped), and failedgodot_apilookups that are a Godot class with a near-miss member, with what was looked up next. Their text, code, names and paths never reach the output, the report or a lesson.
Proposals, numbered, each with an id (stable between runs), its evidence counts and a reason:
| Kind | When | Apply |
|---|---|---|
| draft lesson | a Godot error seen at least twice (review misses plus transcripts) that no rule predicts and no lesson explains | keeps a local lesson tagged draft with the symptom and message; cause and fix are left to write |
| project hint | an API name looked up at least twice that does not exist, with what was found next | adds "use X, not Y" to the project's hints and the lessons for agents |
| lesson from undone writes | writes by the same tool to the same kind of file undone at least twice | keeps a draft lesson about it |
| merge lessons | two local lessons with the same Godot message or nearly the same title | adds the messages, tags and rules of one to the other and removes it |
| retire lesson | a local lesson marked wrong at least twice and more often than it helped | removes it |
| rewrite lesson | a bundled lesson marked wrong here, or a local one shown 10 times with no verdict | a suggestion |
| finish draft | a draft lesson that has been shown twice and still has no fix | a suggestion |
| resolve | findings marked wrong and later right or confirmed by Godot (or the other way round); a rule Godot confirmed whose findings were marked wrong | the newest verdict of each finding wins; the rule one is a suggestion |
| noisy rule | a rule this project marked as a false alarm at least 3 times and at least twice as often as right | a suggestion (findings are not hidden by it) |
godotwright dream # proposals (--detail brief for one line each, --json)
godotwright dream --transcripts --since 7d
godotwright dream --apply 1,3 # numbers or ids; --apply all
godotwright dream --auto-apply yes # once, on this machine: let "auto": "apply" act from the session-start hook
godotwright undo # takes the last apply back, lessons in the learning file includedAn apply writes, through the journal, only on this machine and never into a file of the repository: lessons into the
learning file (through the local-lessons API, so the scrubber applies, and recorded in the journal entry so
godotwright undo puts them back; a lesson rewritten since is left alone), and into the dream folder state.json (the
hints, and the proposals applied or seen: a suggestion comes back once its evidence doubles), a dated report
<date>-<time>.md and lessons-for-agents.md. The dream folder is .godot/godotwright/dreams/ in the project when git
ignores .godot/ (Godot's own .gitignore does) or the project is in no repository; when git would track .godot/, it
is a folder in Godotwright's state folder named by a hash of the project folder, and the journal entry of the apply is
kept there too (godotwright undo still finds it).
lessons-for-agents.md holds the top five recurring mistakes with their fix and up to eight project hints; drafts stay
out of it. Only bundled lessons and local lessons learned in this project go in: a local lesson carries a hash of the
project folder it was kept in (godot_lesson_add, lessons add and dream applies set it), and one from another
project, or kept before this existed, never does. A line that the scrubber would still change (it looks like code or a
name) is left out. An apply that only marks suggestions as seen does not write it. The session-start hook adds it to the
agent's context, on this machine only. The learning file counts Godot errors for the whole machine, so a draft lesson
says where its evidence came from.
When it is due: the session-start hook counts sessions per project (a resumed session once) in Godotwright's state
folder (dreams.json, next to the learning file). Once at least minHours passed and minSessions sessions started
since the last dream (any godotwright dream or godot_dream run), it adds one line: "Godotwright has N dream
proposals: run godot_dream". It reads no transcripts. Settings in godotwright.json (in the project or a folder above
it):
{ "dream": { "auto": "suggest", "minHours": 24, "minSessions": 5 } }"auto": "suggest" (default) only says so; "apply" applies the draft lessons, lessons from undone writes and
project hints by itself (never a removal, merge or verdict change) and says what it did, but only once the person has
allowed it on this machine with godotwright dream --auto-apply yes (--auto-apply no takes that back; an agent
cannot give it through godot_dream); until then it only suggests; "off" stays quiet. Nothing from dreaming is added
to the opt-in anonymous report.
GODOTWRIGHT_LEARN=0 stops the counting.