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.

Navigation Menu

Repository files navigation

Godot Sight

What's in this repo

The 16 MCP tools

Setup

1. Prerequisites

2. Install

3. Install the bridge addon into your Godot project

4. Wire up your MCP client

5. (Cursor only) Install the skills

Smoke test (1 minute)

The Cursor skills

`godot-master` — the engine brain

`godot-sight` — the eyes and hands

`player-writer` — the human play loop

The engine reference library

Architecture

Why a separate supervisor?

Why a bridge addon?

Why a Cursor-skill wrapper?

Project structure

Testing

CLI cheat sheet

Troubleshooting

Compatibility

Roadmap

Acknowledgements

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
cursor-skills		cursor-skills
docs		docs
engine-reference		engine-reference
packages		packages
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTEXT.md		CONTEXT.md
CONTRIBUTING.md		CONTRIBUTING.md
Godot-Sight-Logo.png		Godot-Sight-Logo.png
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

Godot Sight

What's in this repo

The 16 MCP tools

Setup

1. Prerequisites

2. Install

3. Install the bridge addon into your Godot project

4. Wire up your MCP client

5. (Cursor only) Install the skills

Smoke test (1 minute)

The Cursor skills

godot-master — the engine brain

godot-sight — the eyes and hands

player-writer — the human play loop

The engine reference library

Architecture

Why a separate supervisor?

Why a bridge addon?

Why a Cursor-skill wrapper?

Project structure

Testing

CLI cheat sheet

Troubleshooting

Compatibility

Roadmap

Acknowledgements

License

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`godot-master` — the engine brain

`godot-sight` — the eyes and hands

`player-writer` — the human play loop