| name | godot-cache-refresh |
| description | Regenerate Godot caches (class_name registry and .uid files). Use after creating or renaming GDScript files with class_name. |
| allowed-tools | ["Bash"] |
Godot Cache Refresh
Regenerate Godot Engine's project caches by running the editor in headless mode.
What It Refreshes
- Class name cache:
.godot/global_script_class_cache.cfg — registry of all class_name declarations
- UID files:
.uid files for resources that are missing them
When to Use
- After creating new GDScript files with
class_name
- After moving or renaming GDScript files
- When class references are not resolving correctly ("class not found" errors)
Command
<godot> --headless --editor --path <project_root> --quit
<godot> — path to the Godot binary (use whatever is available: godot, godot4, /usr/bin/godot, etc.)
<project_root> — directory containing project.godot
Finding the Project Root
find . -maxdepth 4 -name "project.godot" -type f 2>/dev/null
Success Criteria
Exit code 0 means the cache was regenerated successfully.
Important: Ignore Godot Log Noise
Godot prints WARNING and ERROR messages to stderr during headless runs. These are normal and expected — do not treat them as failures:
WARNING: ObjectDB instances leaked at exit
ERROR: Condition "..." is true
Only the exit code matters.
Role Separation vs godot-resource-resave
This skill is a passive scan: it never rewrites project files, only regenerates caches and missing .gd.uid sidecars. To inject uid= into .tscn / .tres files themselves (and validate that they load), use godot-resource-resave, which actively rewrites those files. When new .gd files are referenced by new scenes, run this skill first so the UID cache is populated, then godot-resource-resave.