Godot Stagehand

Playwright, but for game engines.

Drive your running Godot game from outside the engine. Click real buttons, read real node state, capture real frames and diff them against saved baselines.

One Go binary. Two frontends over the same live connection:

• MCP server. Claude or any other agent plays your game and finds the bugs you would have found by clicking.
• CLI with a scenario runner. The same checks run in CI. JUnit output, stable exit codes, no MCP client anywhere.

See it work: examples/minimal-game is one command. Clone it and watch an agent click a button in a real running Godot scene, then assert the result.

Status: beta, pre-1.0. Prebuilt binaries for Linux, macOS (Intel and Apple Silicon) and Windows. Tool schemas and the wire protocol may still change between minor versions.

Install

# 1. Get the binary (Linux shown; macOS and Windows builds are on the same page)
curl -fsSLo godot-stagehand \
  https://github.com/mrf/godot-stagehand/releases/latest/download/godot-stagehand-linux-amd64
chmod +x godot-stagehand

# 2. Install the addon into your Godot project (idempotent)
./godot-stagehand setup /path/to/your/godot/project

# 3. Run your game with Stagehand on
godot --path /path/to/your/project --stagehand

setup prints the MCP client config snippet and the command to run your game. Your game then prints a one-session auth token. Keep it private, and give it to godot_connect.

Rather not use a terminal? Enable the addon in Project → Project Settings → Plugins, then click Setup… in the editor toolbar. That wizard downloads the binary, writes the config, and tests the connection. Either path is walked through step by step in the Quickstart.

Use it

From an MCP client (Claude Code, Claude Desktop, Cursor, anything speaking MCP):

{
  "mcpServers": {
    "godot-stagehand": {
      "command": "/absolute/path/to/godot-stagehand"
    }
  }
}

From a terminal or a CI job:

export STAGEHAND_AUTH_TOKEN=<the token this Godot session printed>
godot-stagehand find --port 26788 'class:Button' --properties text
godot-stagehand run scenarios/menu-smoke.json --out-dir ci-artifacts

run executes a declarative list of launch, action, wait and assertion steps against a real Godot build and exits nonzero on failure. Exit 5 means a real regression. --out-dir collects report.json, junit.xml, rpc-trace.json, godot.log, screenshots and diff images.

Stagehand binds to 127.0.0.1 and rejects every command until the peer supplies the session token, but it is a dev control plane, not a hardened endpoint. Read the security boundary before you expose anything.

Docs

Quickstart	Install and first command, step by step
Tool reference	Every MCP tool, and what to build with them
CLI and scenario runner	Commands, scenario format, exit codes, CI recipes
Selectors	Targeting nodes by path, name, class, group, text, role
Configuration	Flags, env vars, timeouts, running several agents at once
Security boundary	Auth, remote binding, unsafe methods
Architecture	How the addon, the binary and your client fit together
Compatibility	Godot 4.3 to 4.7, and why not 4.2
Troubleshooting	When it won't connect, or the screenshots are black
Comparison	Versus editor-automation tools and in-engine test frameworks
Visual regression	Baselines, diffing, and the CI gate contract
Agent skill	Drop-in skill file that teaches an agent the whole workflow
Windows / WSL	Bridging Godot on Windows with a client in WSL

Development

go vet ./...          # lint
go test ./...         # Go tests (no Godot needed)
# Scenario runner against a real headless Godot
GODOT_BIN=/path/to/godot go test -tags=godot -run '^TestScenarioRunner' .
# GDScript unit suite (GdUnit4, headless, needs Godot 4.6+)
GODOT_BIN=/path/to/godot ./scripts/run-gdscript-tests.sh

Read the GDScript testing guide for the suite layout and strict-mode rules, the addon sync contract before editing any copy of the addon, and the error model before adding a handler that can fail.

License

MIT. See LICENSE.