Godot Sight

A local runtime evidence system for AI-assisted Godot development.

Godot Sight lets an AI agent (Cursor, Codex CLI, Claude Desktop, or any MCP-compatible client) verify, run, inspect, screenshot, interact with, and report on a Godot 4.x project without leaving the editor flow. The agent stops guessing from source — it sees the actual running game.

┌─────────────┐    MCP    ┌──────────────┐    CLI    ┌──────────────────┐    TCP    ┌─────────────┐
│ AI agent    │ ────────► │ MCP server   │ ────────► │ Python           │ ────────► │ Godot 4.x   │
│ (Cursor,    │           │ (Node.js)    │           │ supervisor       │           │ + bridge    │
│  Codex,...) │ ◄──────── │              │ ◄──────── │ (godot-sight)    │ ◄──────── │ addon       │
└─────────────┘  results  └──────────────┘  json     └──────────────────┘  events   └─────────────┘

---

What's in this repo

Directory	What it is	Status
packages/supervisor/	Python CLI + process supervisor. Exposes runtime, playtest, and Playwrite commands.	Working
packages/mcp-server/	TypeScript MCP server that wraps the supervisor as 16 MCP tools.	Working
packages/godot-addon/	Godot bridge addon. Listens on 127.0.0.1:8765.	Working
packages/examples/	6 example Godot projects + sample MCP client configs.	Working
cursor-skills/	Cursor skills + agent briefs + path-scoped rules that make the agent use this system correctly.	Working
engine-reference/	Version-pinned Godot 4.6 quick references that fill the LLM's training-data gap.	Working

The runtime system (packages/) is MCP-client agnostic — works with any client. The Cursor skills are Cursor-specific but the patterns transfer to any agent framework with a skills / instructions system.

---

The 16 MCP tools

Tool	What it does
godot_sight_doctor	Validate prerequisites: Godot binary, supervisor CLI, project path, port availability.
godot_sight_project_info	Read project.godot, list scenes, autoloads, input map.
godot_sight_verify_project	Headless godot --check-only parse; surface errors with category classification.
godot_sight_run_scene	Launch a scene with the bridge enabled.
godot_sight_stop	Stop the running Godot process and release the bridge port.
godot_sight_get_logs	Read recent stdout + stderr, classified into error / warn / info buckets.
godot_sight_get_runtime_state	Inspect the managed game process: running, pid, run_id, scene, started_at, logs.path. Cross-platform live PID check.
godot_sight_get_scene_tree	Walk the live scene tree (paths, classes, properties).
godot_sight_screenshot	Capture a PNG from the running viewport.
godot_sight_input_action	Trigger an InputMap action with optional duration.
godot_sight_run_playtest	Execute a deterministic playtest from a .yml file.
godot_sight_playwrite_capture_start	Start a focused gameplay capture session that records a Draft Playwrite.
godot_sight_playwrite_capture_stop	Stop capture and write the Draft Playwrite, including shutdown-draft recovery if the game was closed.
godot_sight_playwrite_replay	Replay a .playwrite.yml through the bridge and return structured replay evidence.
godot_sight_playwrite_promote	Promote a verified Playwrite into a Wrapper Playtest with selected Evidence Checkpoints.
godot_sight_latest_report	Read the most recent run's structured report.

Each tool's full argument and response shape is described in packages/mcp-server/src/tools.js and cursor-skills/skills/godot-sight/reference.md.

---

Setup

1. Prerequisites

• Python 3.11+
• Node.js 24+ (and npm 11+)
• Godot 4.x (tested on 4.6.1; 4.4+ should work for non-4.6-specific features)
• An MCP-compatible client — Cursor, Codex CLI, Claude Desktop, etc.

2. Install

git clone https://github.com/Lanc3/godot-sight.git
cd godot-sight

# Install Node deps (MCP server)
npm install

# Install the Python supervisor as a CLI
python -m pip install -e packages/supervisor

# Verify CLI is on PATH
godot-sight doctor --json

If godot-sight doctor returns a JSON result with "status": "ok", the supervisor is installed. If it complains about a missing Godot binary, set the GODOT_SIGHT_GODOT_PATH env var to the absolute path of your Godot executable.

3. Install the bridge addon into your Godot project

godot-sight install-addon --project /path/to/your/godot/project --json

Then in the Godot editor: Project → Project Settings → Plugins and enable Godot Sight Bridge.

The addon listens on 127.0.0.1:8765 whenever your game runs. It is safe to leave enabled — no traffic leaves the loopback interface.

4. Wire up your MCP client

Copy one of the example configs and replace placeholder paths:

• Cursor: packages/examples/mcp/cursor.mcp.json → <your-project>/.cursor/mcp.json
• Codex CLI: packages/examples/mcp/codex.mcp.json → wherever your client reads MCP configs

See packages/examples/mcp/README.md for per-OS examples and a list of placeholders to replace.

Restart your MCP client. The 16 tools should appear in the client's tool list, prefixed with godot_sight_.

5. (Cursor only) Install the skills

The Cursor skills make the agent use Godot Sight correctly — proactively, without you asking — and pair it with the engine reference library.

# From the repo root
cp -r cursor-skills/skills/godot-master  /path/to/your/project/.cursor/skills/
cp -r cursor-skills/skills/godot-sight   /path/to/your/project/.cursor/skills/
cp -r cursor-skills/skills/player-writer /path/to/your/project/.cursor/skills/
mkdir -p /path/to/your/project/.cursor/agents
cp     cursor-skills/agents/godot-*.md   /path/to/your/project/.cursor/agents/
mkdir -p /path/to/your/project/.cursor/rules
cp     cursor-skills/rules/*.mdc         /path/to/your/project/.cursor/rules/
cp -r  engine-reference/godot            /path/to/your/project/docs/engine-reference/

Full step-by-step in cursor-skills/README.md.

---

Smoke test (1 minute)

Once everything is wired up, ask your agent:

"Run godot_sight_doctor and show me the result."

Expected: a JSON-shaped response with status: ok and the four checks (godot, supervisor, project, port) all green.

Then:

"Run scene res://Main.tscn in my project, screenshot it, and stop."

Expected: the agent calls godot_sight_run_scene → waits a few seconds → godot_sight_screenshot → godot_sight_stop. You get a PNG path back.

If that works, you have the whole loop.

---

The Cursor skills

Three skills, designed to be used together:

godot-master — the engine brain

Routes the agent to the right reference doc, specialist, or path-scoped rule before suggesting any Godot API. Auto-triggers on any Godot file edit (.gd, .tscn, .gdshader, .tres, project.godot).

• Core loop: KNOW → ROUTE → DELEGATE? → ACT → VERIFY → RECORD
• 14 per-subsystem playbooks (GDScript, shaders, scenes, UI, physics 2D & 3D, audio, animation, resources, autoloads, editor & tooling, performance, networking, navigation)
• Specialist delegation rules
• Anti-patterns
• Drift schedule + ownership table

See cursor-skills/skills/godot-master/SKILL.md.

godot-sight — the eyes and hands

Drives the MCP tools as the agent's runtime verification loop. Auto-triggers on any code edit; runs VERIFY → RUN → SEE → ASSERT → STOP without being asked.

• 7 scenario playbooks (new feature, visual bug, script bug, UI polish, refactor, pre-commit, regression check)
• Playtest YAML grammar + recipes
• Decision tree for "what to call next"

See cursor-skills/skills/godot-sight/SKILL.md.

player-writer — the human play loop

Guides a user through Playwrite Capture, immediate replay, and optional promotion into a Wrapper Playtest. Use it when the right test starts with a real person playing the game rather than hand-authoring YAML.

• Captures keyboard and mouse gameplay into Draft Playwrites.
• Shows an in-game capture overlay with live captured input feedback.
• Recovers capture when the managed game closes during recording.
• Uses Structured Confirmations before replay, promotion, and checkpoint selection.

See cursor-skills/skills/player-writer/SKILL.md.

The skills compose: godot-master is the brain, godot-sight is the eyes and hands. The brain tells you what to do; the eyes and hands let you prove it actually happened. player-writer adds the human playtesting loop: capture a real interaction, replay it, and promote it into durable regression evidence.

---

The engine reference library

engine-reference/godot/ contains version-pinned Godot 4.6 quick references. It exists because LLM training data has a cutoff, and game engines update faster than models.

File	What it covers
VERSION.md	Pinned version + knowledge gap window
breaking-changes.md	API changes 4.3 → 4.6
deprecated-apis.md	"Don't use X → Use Y" lookup
current-best-practices.md	Post-cutoff additions (variadic args, @abstract, Jolt default, dual-focus UI, AgX tonemapper, duplicate_deep, etc.)
modules/	10 per-subsystem quick references: ui, rendering, physics, physics-2d, input, audio, animation, networking, navigation, editor-tooling

Each module is ≤150 lines (context budget), has a "Last verified" date, and cites official Godot docs URLs for every claim.

When Godot 4.7 ships: bump VERSION.md, add a 4.6 → 4.7 row to breaking-changes.md, move newly-deprecated APIs into deprecated-apis.md, update affected modules. A refresh skill drives this — see cursor-skills/skills/setup-engine/ if you use the full CCGS template, or just hand-maintain.

---

Architecture

Why a separate supervisor?

The MCP server is intentionally thin: it converts MCP tool calls into subprocess invocations of the godot-sight CLI. The supervisor does the real work — process management, log parsing, bridge TCP, playtest execution.

This separation means:

• The supervisor is usable directly from a shell, CI, or pytest — not just MCP.
• The MCP server has no Godot-specific logic; it's a generic adapter.
• Each layer is independently testable. Supervisor tests don't need the MCP layer; MCP tests don't need a real Godot binary.

Why a bridge addon?

Some tools need data Godot doesn't expose via CLI (live scene tree, viewport screenshot, input injection). The bridge addon opens a TCP socket on 127.0.0.1:8765 and answers JSON requests from the supervisor while the game runs.

The bridge does not open a remote socket. It is loopback-only. There is no authentication because there is no remote attack surface.

Why a Cursor-skill wrapper?

The MCP tools alone are powerful but the model has to remember to use them. A skill with proactive triggers makes the agent use the loop automatically: every Godot edit ends with a Sight round, every Godot API suggestion is gated by a deprecation check.

You don't have to use the skills — the raw MCP tools work in any client. The skills just remove the cognitive overhead of remembering to invoke them.

---

Project structure

godot-sight/
├── README.md                       ← this file
├── LICENSE                         ← MIT
├── CONTRIBUTING.md
├── CHANGELOG.md
├── package.json                    ← npm workspace root
│
├── packages/
│   ├── supervisor/                 ← Python CLI + supervisor
│   │   ├── pyproject.toml
│   │   ├── src/godot_sight_supervisor/
│   │   │   ├── cli.py              ← runtime, playtest, and Playwrite commands wired here
│   │   │   ├── bridge.py           ← TCP client for the addon
│   │   │   ├── doctor.py
│   │   │   ├── verify.py
│   │   │   ├── project_info.py
│   │   │   ├── run_stop.py
│   │   │   ├── logs.py
│   │   │   ├── scene_tree.py
│   │   │   ├── screenshot.py
│   │   │   ├── input.py
│   │   │   ├── playtest.py
│   │   │   ├── playwrite.py        ← capture, replay, promote
│   │   │   ├── playwrite_replay_plan.py
│   │   │   ├── run_artifacts.py    ← shared evidence output helpers
│   │   │   ├── report.py
│   │   │   └── addon.py            ← `install-addon` command
│   │   └── tests/                  ← pytest, one file per module
│   │
│   ├── mcp-server/                 ← TypeScript MCP server
│   │   ├── package.json
│   │   ├── src/
│   │   │   ├── server.js           ← MCP stdio transport
│   │   │   └── tools.js            ← 16 tool definitions + arg schemas
│   │   └── test/                   ← Node native test runner
│   │
│   ├── godot-addon/
│   │   └── addons/godot_sight_bridge/
│   │       ├── plugin.cfg
│   │       ├── godot_sight_bridge_plugin.gd    ← editor-side (@tool)
│   │       └── godot_sight_bridge.gd           ← runtime TCP server
│   │
│   └── examples/
│       ├── mcp/                    ← cursor.mcp.json, codex.mcp.json, README
│       ├── minimal_project/        ← trivial Godot project for smoke tests
│       ├── broken_script_project/  ← parse-error project for verify tests
│       ├── input_project/          ← input-driven project for action tests
│       ├── playtest_project/       ← project with example .yml playtests
│       └── agent_loop_project/     ← end-to-end agent scenario fixture
│
├── cursor-skills/
│   ├── README.md                   ← install instructions
│   ├── skills/
│   │   ├── godot-master/{SKILL,reference,playbooks}.md
│   │   ├── godot-sight/{SKILL,reference,playtests}.md
│   │   └── player-writer/{SKILL,smoke}.md
│   ├── agents/
│   │   └── godot-{specialist,gdscript-specialist,shader-specialist,
│   │              csharp-specialist,gdextension-specialist}.md
│   └── rules/
│       └── {engine-code,gameplay-code,shader-code,ui-code}.mdc
│
└── engine-reference/
    ├── README.md
    └── godot/
        ├── VERSION.md
        ├── breaking-changes.md
        ├── deprecated-apis.md
        ├── current-best-practices.md
        └── modules/
            ├── ui.md
            ├── rendering.md
            ├── physics.md          ← 3D
            ├── physics-2d.md
            ├── input.md
            ├── audio.md
            ├── animation.md
            ├── networking.md
            ├── navigation.md
            └── editor-tooling.md

---

Testing

# Full Python supervisor suite
python -m pytest packages/supervisor/tests

# MCP server suite (Node native test runner)
npm test --workspace packages/mcp-server

# End-to-end agent loop scenario
python -m pytest packages/supervisor/tests/test_agent_loop.py

---

CLI cheat sheet

Once the supervisor is installed (pip install -e packages/supervisor), all the same operations are available from a shell:

godot-sight doctor --json
godot-sight project-info --project <path> --json
godot-sight verify --project <path> --json
godot-sight run --project <path> --scene res://main.tscn --json
godot-sight stop --project <path> --json
godot-sight runtime-state --project <path> --json
godot-sight logs --project <path> --json
godot-sight scene-tree --project <path> --json
godot-sight screenshot --project <path> --json
godot-sight input --project <path> --action ui_accept --duration-ms 100 --json
godot-sight playtest --project <path> --file <playtest>.yml --json
godot-sight playwrite capture start --project <path> --name menu-flow --json
godot-sight playwrite capture stop --project <path> --name menu-flow --json
godot-sight playwrite replay --project <path> --file <playwrite>.playwrite.yml --json
godot-sight playwrite promote --project <path> --file <playwrite>.playwrite.yml --verified-run <result.json> --json
godot-sight report latest --project <path> --json
godot-sight bridge-ping --host 127.0.0.1 --port 8765 --json
godot-sight install-addon --project <path> --json

The MCP server wraps these one-to-one, so a tool call is roughly equivalent to its CLI invocation.

---

Troubleshooting

Symptom	Likely cause	Fix
godot_sight_doctor reports godot: missing	GODOT_SIGHT_GODOT_PATH not set, or Godot not on PATH	Set the env var to the absolute path of your Godot binary
godot_sight_doctor reports supervisor: missing	Supervisor CLI not on PATH	pip install -e packages/supervisor, then check which godot-sight (Unix) or Get-Command godot-sight (PowerShell)
Bridge tools time out with "connection refused"	The bridge addon isn't enabled in your Godot project, or the previous game didn't release port 8765	Re-enable the addon in Project Settings → Plugins; or godot_sight_stop to free the port
godot_sight_run_scene works but get_scene_tree returns empty	The game hasn't fully loaded yet	Wait 5–8 seconds after run_scene before calling bridge tools
Playtest YAML returns unsupported for some step kinds	Step kind is misspelled or not in the v0.9.0 contract (the 8 shipped: wait_ms, input_action, assert_node_exists, assert_node_visible, assert_text_contains, mouse_click, assert_position_changed, screenshot)	See docs/features/playtest-contract.md for the full grammar
Playwrite replay reports contamination	Real input reached the game during replay, or replayed input was not recognized as expected	Do not touch mouse or keyboard during replay; inspect the replay report for contamination counts and warnings
Capture ended because the game closed	This is supported for managed runs	Run capture stop; the supervisor will recover the shutdown draft from .godot_sight/playwrites/ when available
Cursor not auto-triggering the skills	Skills not installed into .cursor/skills/ or Cursor not restarted	Verify file presence; restart Cursor

---

Compatibility

• Tested: Windows 10, Node.js 24.x, Python 3.11, Godot 4.6.1
• Should work: macOS, Linux, Node.js 22+, Python 3.10+, Godot 4.4+
• Untested but documented: alternative MCP clients (Claude Desktop, custom)

The supervisor uses cross-platform pathlib / subprocess. The bridge uses standard Godot TCP. There is no platform-specific code in any package.

---

Roadmap

This is a v0.9.0 release candidate. The roadmap to 1.0.0:

• 0.9.x — public testing, cross-platform smoke tests (macOS / Linux), bug fixes from community feedback
• 1.0.0 — hardened Player Writer ergonomics, additional playtest step kinds (assert_property, assert_signal_fired, wait_for_signal), Godot 4.7 reference upgrade, npm + PyPI publishing

Future considerations:

• Unity / Unreal equivalents of the engine reference library (separate packages)
• Multiplayer scenario coverage (two-instance playtests)
• CI integration (run playtest YAML as part of GitHub Actions)
• Web-based dashboard for .godot_sight/runs/ evidence
• Richer Playwrite promotion assistance for choosing Evidence Checkpoints

---

Acknowledgements

• The Model Context Protocol team for the agent-host integration spec.
• The Godot Engine team for an editor that's actually fun to write tooling for.

---

License

MIT — see LICENSE.