Overview

Swallowtail is an automation toolkit for Godot. Inspect scenes, edit projects, run checks, and playtest from your terminal. Reuse the same commands in your scripts and connect them to your other tools.

Use swallowtail for new commands. The deprecated godot-mcp executable still ships in the same bundle. To move an existing addon installation, follow Migrating to Swallowtail.

Start where you work#

• Run commands: follow the terminal quickstart to build and play a scene in a fresh project.
• Automate your workflow: compose commands with JSON, exit codes, and shell scripts in Scripting and CI.
• Connect your tools: use the CLI directly, or configure the optional MCP interface.

Alongside Godot’s CLI#

Godot’s built-in command line handles engine startup, scripts, imports, and exports. Swallowtail invokes your installed engine for those jobs and adds commands for the open editor and running game. See How it works.

The working loop#

discover → build → run → play → observe → debug → fix → verify

Because the CLI talks to the live editor and game, each stage can verify the previous one against real state. Ask the engine what it supports, read changes back, drive gameplay through input, and use the debugger when behavior differs from what you intended.

# 1. discover: ask the live ClassDB what exists
swallowtail engine search --query offset_transform

# 2. build: act through typed or generic commands
swallowtail node set --node-path Player --property position --value "Vector2(100, 200)"

# 3. run and play
swallowtail scene play --mode main
swallowtail input action --action ui_accept --pressed true

# 4. observe and verify
swallowtail runtime get --node-path Player --properties '["position"]'
swallowtail runtime errors

Where to go next#

Requirements at a glance#

• Godot 4.7, the development target. 4.3 through 4.8 work in beta; see Installation.
• Go 1.26+ to build the CLI (or use a release binary).
• The editor must be open with the Swallowtail plugin enabled; the CLI is a short-lived client that dials in per command.