Installation

Requirements#

• Godot 4.7, the version this is developed and released against. 4.3 through 4.8 work in beta.
• Go 1.26+ to build the CLI, or a prebuilt release binary.

Download and unpack the bundle for your OS and CPU from the releases page. Add the directory containing the CLI to PATH, keeping its addons/ directory beside it. On Windows the binary is swallowtail.exe. Go is only needed to build from source. No agent or MCP configuration is required.

Into an existing project#

From an unpacked release bundle, install the addon into any Godot project:

swallowtail install --project /path/to/your/project --enable --skill=false

This copies addons/swallowtail/ and enables the plugin in project.godot, including the two game-side autoloads the runtime and input groups need. Enabling from the editor’s plugin checkbox injects the same pair, so nothing needs pre-committing either way.

Omit --skill=false to also install the optional agent skill. The terminal quickstart builds and plays a scene from an empty project.

Bootstrap a new project#

Starting from nothing? Create a fresh Godot 4.7 project and wire the addon in one command:

swallowtail create --path ./mygame --install --enable

Writes a project.godot (config version 5, 4.7 feature tag), an original placeholder icon.svg, and a .gitignore. It never overwrites an existing project.godot.

Build the CLI from source#

go build -o bin/swallowtail ./cmd/swallowtail
# or, with Task installed:
task build          # -> bin/swallowtail(.exe)

Pin the MCP port (per project)#

The addon binds the first free port in 9080-9095 and writes it to .godot/swallowtail.json, so the CLI auto-discovers it and you rarely think about ports. Running two projects at once, pin each to a distinct port so they never contend: Project → Project Settings → Swallowtail → Network → Port (turn on Advanced Settings to see it). Set an explicit port; 0, the default, means auto-pick.

The value is saved in that project’s project.godot, so two concurrent projects listen deterministically on their own ports. SWALLOWTAIL_PORT in the environment still overrides everything, and the default 0 is never written to project.godot, so leaving the setting alone keeps the file clean.

Bundled greybox assets (optional)#

Copy the bundled CC0 asset packs into a project for prototyping:

swallowtail install-assets --list
swallowtail install-assets --pack kenney_prototype_textures

Before you ship#

The addon must not ride into an exported game. Before you ship has the two steps and the pck scan that proves they worked.

Troubleshooting#

If the CLI can’t connect, run the environment preflight:

swallowtail doctor

It checks the godot binary and version, that the project resolves, whether the addon is installed and enabled, the effective port source (env, per-project pin, or auto), whether an editor is actually reachable, and the .NET SDK on C# projects. Pass --project DIR to target a specific project, or --json for machine-readable output. It exits non-zero only when a check fails; a warning (no editor running yet, say) doesn’t fail the run, so doctor is safe to run before you’ve launched anything.