<p align="center"> <img src="Godot-Sight-Logo.png" alt="Godot Sight" width="512"/> </p>

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_sup