Use the CLI
Run commands from your terminal, reuse them in scripts, or add them to CI. Read the results directly, or pipe JSON into your next step.
Command referenceAUTOMATION FOR GODOT
SwallowtailAt your service.
Build, inspect, and playtest your game. Put the repetitive work in a script. Keep the creative decisions yours.
Your game. Your workflow.
Run swallowtail from your terminal. Upgrading from godot-mcp?
Windows, macOS, Linux · Godot 4.7 target
Godot 4.3 through 4.8 compatibility in beta · Installation & requirements
$ swallowtail scene tree
Hello (Node2D) .
└─ Greeting (Label) Greeting
$ swallowtail check .
Same toolkit.
Your way of working.
$ swallowtail scene tree
Player (CharacterBody2D) .
├─ Col (CollisionShape2D) Col
└─ Body (ColorRect) Body
$ swallowtail node add --type Camera2D --name Cam --parent Player
╭─ node.add ───────────╮
index 2
name Cam
node_path Cam
type Camera2D
╰──────────────────────╯
$ swallowtail node set --node-path Player/Cam --property zoom --value "Vector2(2, 2)"
╭─ node.set ──────────────────────────────╮
new_value {"x":2.0,"y":2.0}
node Cam
old_value {"x":1.0,"y":1.0}
property zoom
╰─────────────────────────────────────────╯
$ swallowtail scene save
╭─ scene.save ────────────────────────╮
path res://player.tscn
saved true
╰─────────────────────────────────────╯
$ swallowtail scene tree
Player (CharacterBody2D) .
├─ Col (CollisionShape2D) Col
├─ Body (ColorRect) Body
└─ Cam (Camera2D) Cam
$ cat plan.json
{"steps": [
{"method": "engine.version", "expect": {"/version/major": 4}},
{"method": "scene.validate", "params": {"path": "res://player.tscn"},
"expect": {"/valid": true}},
{"method": "script.validate", "params": {"path": "res://player.gd"},
"expect": {"/valid": true}},
{"method": "project.info", "expect": {"/godot_version/minor": 7}}
]}
$ swallowtail automate --file plan.json | jq -r '.steps[] | [.status, .method] | @tsv'
passed engine.version
passed scene.validate
passed script.validate
passed project.info
# a wrong expectation stops the plan, and the exit code says so
$ swallowtail automate --file strict.json > report.json; echo $?
1
$ jq -c '.steps[] | {method, status, error: .error.kind}' report.json
{"method":"scene.validate","status":"failed","error":"assertion"}
{"method":"scene.save","status":"skipped","error":null}
# two files in res://mcp_commands/ add four project commands
$ swallowtail custom --help
swallowtail custom: 4 commands (addon catalog):
broken_refs Report res:// paths and uid:// ids that no longer resolve.
echo Echo --message back to the caller.
ping Health check: returns {pong: true}.
replace_ref Repoint every reference from one resource to another, uid included.
$ swallowtail custom broken-refs --help
Params:
--path String optional Directory to scan (default res://).
--include-addons bool optional Scan addons/ too (default false).
--limit int optional Max findings per list (default 200).
$ swallowtail custom broken-refs
╭─ custom.broken_refs ──────────────────────────────────╮
broken []
broken_count 0
checked_refs 27
dynamic_count 1
scanned_files 10
truncated false
╰───────────────────────────────────────────────────────╯
# the same command is an MCP tool, schema included
$ swallowtail engine commands --group custom | jq '.count'
4
$ swallowtail status | jq -c '{verdict, port, project_match}'
{"verdict":"running","port":9080,"project_match":true}
$ swallowtail configure claude --project . --print
Would write to: /games/my-game/.mcp.json
{
"mcpServers": {
"swallowtail": {
"command": "swallowtail",
"args": ["serve", "--project", "/games/my-game"]
}
}
}
# or skip the process: the editor hosts an MCP endpoint itself
$ curl -s -X POST http://127.0.0.1:9100/mcp -H 'Content-Type: application/json' \
> -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'
337
PUT IT TO WORK
Before your next build.
Check your scripts, validate a saved scene, and inspect errors from a short playtest. Keep the commands with your project so you can repeat the checks after a change.
Try this from the quickstart project, with its editor open and the addon enabled. Use your own saved scene path when you adapt it.
Turn it into a CI checkswallowtail check .swallowtail scene validate --path res://hello.tscnswallowtail scene play --mode res://hello.tscnswallowtail runtime errorsswallowtail scene stopRead the validation results and returned error list before exporting. This sequence inspects a playtest; a CI gate also needs assertions and failure handling.
CLI first.
MCP when you want it.
MCP is a connection option. The automation toolkit works without it.
Connect through MCP
For clients that use MCP, expose the same command handlers through stdio or the editor's HTTP endpoint. Configure this only if your workflow needs it.
Optional MCP setupKEEP CONTROL OF YOUR WORK
Your project stays yours.
Work with ordinary Godot scenes, scripts, and resources. Open them in the editor, review the changes in Git, and keep building with the tools you choose.
Inspect what changes
Your scenes, scripts, and resources remain project files you can read, edit, and version.
Undo supported scene edits
Supported scene operations use Godot's editor undo history. Script execution and file changes need their own review and recovery.
Keep a checkpoint
Save your work and commit a known working state before broad changes. Review the diff and test the result before keeping it.
Godot already has a CLI.
Swallowtail works with it.
Godot's built-in command line launches the engine and handles tasks such as imports, scripts, and exports. Swallowtail uses your Godot installation for those jobs and adds an interface to the editor session you already have open.
Start with the engine
Import assets, check scripts, run tests, and export builds through commands that invoke Godot and report the result.
swallowtail check .Work in the live editor
Inspect the scene tree, change node properties, and validate saved scenes. Read state back as you work.
swallowtail scene treeSee what the game does
Play a scene, inspect runtime properties, send input, and check errors. Verify behavior in the running game.
swallowtail runtime treeSwallowtail uses an installed Godot engine; it does not bundle one. Godot's command-line reference · How Swallowtail works
HOW IT COMPARES
Swallowtail next to
Godot AI and Godot MCP Native.
What each tool documents: how you start, what you set up, and what you can run from a terminal, a script, or an MCP client. Sources and the comparison date sit under the table.
| What you need | Swallowtail | Godot AI | Godot MCP Native |
|---|---|---|---|
| Starting point | Standalone automation CLI + editor addon | MCP integration for the editor | MCP editor addon + companion CLI |
| Run from your terminal | Use swallowtail directly, without MCP | Documented setup uses godot-ai attach to connect an MCP client | Use gdmcp through its separate local CLI API |
| Use without an AI agent | Yes. The CLI and scripts need no agent, model, or account | Its requirements list an MCP client; every documented workflow runs through one | Yes, through its gdmcp CLI, which the docs present for agents with shell access |
| Set up the connection | Go binary + Godot addon for live commands | Python server via uv + Godot plugin + MCP client | Godot addon; prebuilt CLI for terminal use |
| Automate a workflow | Create projects, import, check, test, export, and operate the live editor | Edit scenes and scripts, run projects and test suites through MCP tools | Discover tools, run domain commands, and preview or apply command batches |
| Inspect a playtest | Runtime state, input, captures, breakpoints, stepping, and hot reload | Game state, input sequences, screenshots, and error logs | Runtime probe, breakpoints, stack and variable inspection, and execution control |
| Connect an MCP client | Optional stdio or editor-hosted HTTP interface | Documented primary workflow | MCP interface alongside the separate CLI API |
Compared against the published documentation on September 7, 2026: Godot AI, its tool reference, Godot MCP Native, and its CLI reference. This summarizes documented workflows, not an exhaustive feature audit.
WHY THIS PROJECT EXISTS
I just wanted
to build games.
For my son.
For myself.
After twenty years as a programmer, I wanted to spend more time making games. I don't have the budget to hire a team for every idea, and I don't want to spend ten years on a project at the expense of my health or my family.
What I wanted was a toolkit that lets me work the way I want on any given day, and that includes using AI as one of the tools. Some days that is a terminal and a script I can run again. Some days it is an agent driving the editor while I review what it changed. Swallowtail gives both the same commands, so the choice stays mine at every step between an idea and something you can actually play.
I understand the concerns about this technology. You don't have to agree with my choices, and I respect that. I'm here to make games and share a tool, not to fight. Questions and criticism are welcome. Bullying and personal attacks aren't.
The full note on AI and this project