### Setup Development Environment

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Commands to set up the Python virtual environment, install dependencies, and run linters/formatters. Ensure you are in the project root directory.

```bash
cd ~/godot-ai
script/setup-dev             # creates .venv, installs deps, applies macOS .pth fix
source .venv/bin/activate
pytest -v                    # run tests
ruff check src/ tests/       # lint
ruff format src/ tests/      # format
```

--------------------------------

### Install uv with Homebrew

Source: https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/README.md

Install uv using the Homebrew package manager on macOS or Linux.

```bash
brew install uv
```

--------------------------------

### Install uv with pipx

Source: https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/README.md

Install uv using pipx, a tool for installing and running Python applications in isolated environments.

```bash
pipx install uv
```

--------------------------------

### Install uv on Windows (PowerShell)

Source: https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/README.md

Execute this PowerShell command to install the uv package manager on Windows.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Setup Development Environment (macOS/Linux)

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/CONTRIBUTING.md

Clone the repository, set up the development environment including virtual environment, dependencies, and plugin symlink, and activate the virtual environment.

```bash
git clone https://github.com/hi-godot/godot-ai.git
cd godot-ai
script/setup-dev             # creates .venv, installs deps, builds plugin symlink, installs git hooks
source .venv/bin/activate
```

--------------------------------

### Setup Development Environment (Windows PowerShell)

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/CONTRIBUTING.md

Clone the repository, set up the development environment including virtual environment, dependencies, and plugin junction, and activate the virtual environment.

```powershell
git clone https://github.com/hi-godot/godot-ai.git
cd godot-ai
.
script\setup-dev.ps1       # creates .venv, installs deps, builds plugin junction, installs git hooks
.venv\Scripts\Activate.ps1
```

--------------------------------

### Install uv on macOS / Linux

Source: https://github.com/hi-godot/godot-ai/blob/main/plugin/addons/godot_ai/README.md

Use this command to install the uv package manager on macOS and Linux systems.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install uv Package Manager (Debian/Ubuntu)

Source: https://github.com/hi-godot/godot-ai/blob/main/README.md

Installs the uv package manager using apt on Debian/Ubuntu. For older releases, pipx or the script method may be necessary.

```bash
sudo apt install uv
```

--------------------------------

### Install uv Package Manager (Fedora)

Source: https://github.com/hi-godot/godot-ai/blob/main/README.md

Installs the uv package manager using dnf on Fedora. Requires sudo privileges.

```bash
sudo dnf install uv
```

--------------------------------

### Install uv Package Manager (Arch Linux)

Source: https://github.com/hi-godot/godot-ai/blob/main/README.md

Installs the uv package manager using pacman on Arch Linux. Requires sudo privileges.

```bash
sudo pacman -S uv
```

--------------------------------

### Run Dev Server with Auto-Reload

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/CONTRIBUTING.md

Start the development server for Python-side changes without restarting Godot, using streamable HTTP transport on a specified port.

```bash
python -m godot_ai --transport streamable-http --port 8000 --reload
```

--------------------------------

### Python Handler Command Example

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Example of how to send a command from a handler in Python. Errors should not be handled directly within the handler.

```python
await runtime.send_command("command_name", params)
```

--------------------------------

### Run Default Stress Test

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/STRESS_TESTING.md

Executes the default stress test with approximately 1000 calls. This is the basic command to start testing.

```bash
python script/stormtest.py
```

--------------------------------

### Reconfigure MCP Client with New Port

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/port-conflicts.md

Example of how to remove and re-add an MCP client using the command line to point to a new server port. This is useful when the Godot AI server's port has been changed.

```bash
claude mcp remove godot-ai
claude mcp add --scope user --transport http godot-ai http://127.0.0.1:8001/mcp
```

--------------------------------

### Example of Captured Log Data (Bugged)

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/friction-log.md

This JSON snippet shows the output from push_warning when the logging mechanism incorrectly discards the user's message. It highlights the issue where the rationale is empty and the format string leads to unexpected output.

```json
{ "level": "warn", "text": " (core/variant/variant_utility.cpp:1034 @ push_warning)" }
```

--------------------------------

### Example Telemetry Record Structure

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/TELEMETRY.md

This JSON object represents a typical telemetry record, detailing tool execution events. It includes identifiers, timestamps, version information, and specific data about the tool's performance and platform.

```json
{
  "record": "tool_execution",
  "timestamp": 1736294400.123,
  "customer_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "3f1a8b22@a3f2",
  "version": "0.0.41",
  "platform": "Darwin",
  "source": "darwin",
  "data": {
    "tool_name": "scene_manage",
    "sub_action": "save_as",
    "success": true,
    "duration_ms": 12.7,
    "platform_detail": "Darwin 24.0.0 (arm64)",
    "python_version": "3.11.10"
  }
}
```

--------------------------------

### Python DirectRuntime Initialization

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Tools should create a DirectRuntime instance from the context and delegate operations to handlers.

```python
DirectRuntime.from_context(ctx)
```

--------------------------------

### Recipe for Testing Runtime UI with editor_screenshot

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/screenshot-testing.md

This sequence outlines the steps to test runtime UI elements, such as a main menu, using `editor_screenshot`. It emphasizes waiting for the `game_capture_ready` signal before requesting a screenshot and stopping the project run afterward.

```text
1. editor_state                              -> confirm session, current_scene, readiness="ready"
2. project_run(mode="current",               -> autosave=False so MCP scene mutations stay in memory
              autosave=False)
3. poll editor_state every ~500ms            -> wait until is_playing=true AND game_capture_ready=true
4. (interact via available write tools as    -> e.g. node_set_property, batch_execute,
    needed for the scenario being tested)       ui_manage, theme_manage
5. editor_screenshot(source="game",          -> request the capture
                     max_resolution=1280)
6. project_manage(op="stop")                 -> always stop the run when done
```

--------------------------------

### Updating Server Instructions

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

If the new verb is named, update the tool-surface blurb in `server.py`'s `instructions=` argument.

```python
instructions="""
... (updated instructions)
"""
```

--------------------------------

### Example Domain Rollup Call

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/TOOLS.md

This is an example of a JSON object representing a call to a domain rollup tool. The 'op' field specifies the operation, and 'params' contains the arguments for that operation. The 'op' field uses a Literal enum for schema-aware autocomplete.

```json
{"op": "set_color", "params": {"theme_path": "res://theme.tres",
                                "class_name": "Label", "name": "font_color",
                                "value": "#ff0000"}}
```

--------------------------------

### Serve Worktree Convenience Wrappers

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/STRESS_TESTING.md

Provides platform-specific convenience wrappers for serving a worktree. Use these for easier command execution on macOS, Linux, or Windows.

```bash
script/serve-this-worktree --port 8000 --ws-port 9500        # macOS / Linux
```

```powershell
.\script\serve-this-worktree.ps1 --port 18130 --ws-port 19630  # Windows (PowerShell)
```

--------------------------------

### Create Feature Branch and Push

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/CONTRIBUTING.md

Create a new feature branch, ensure tests and linting pass, and push the branch to the remote repository.

```bash
git checkout -b feature/my-feature
```

```bash
pytest -v && ruff check src/ tests/
```

```bash
git push -u origin feature/my-feature
```

```bash
gh pr create
```

--------------------------------

### Server-Side Components Overview

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/plugin-architecture.md

Lists the main Python modules on the server-side that correspond to the plugin's functionality. This helps in understanding the backend architecture and how it interacts with the plugin.

```text
Server-side counterparts live in:

- `src/godot_ai/server.py` — FastMCP entry point, lifespan, tool/resource registration, `--exclude-domains`
- `src/godot_ai/asgi.py` — uvicorn factory for `--reload`; ships `StaleMcpSessionDiagnosticMiddleware`
- `src/godot_ai/transport/websocket.py` — WebSocket server adopting/owning the :9500 socket
- `src/godot_ai/sessions/registry.py` — multi-session tracking, active resolution, substring matching
- `src/godot_ai/godot_client/client.py` — typed async client; raises `GodotCommandError`
- `src/godot_ai/runtime/direct.py` — `DirectRuntime`, the in-process runtime adapter that handlers depend on
- `src/godot_ai/handlers/` — shared sync handlers; `_readiness.py` gates writes; `_target.py` resolves nodes
- `src/godot_ai/tools/` — MCP tool wrappers per domain + `_meta_tool.py::register_manage_tool` rollup factory + `domains.py` (CI-paired with `tool_catalog.gd`)
- `src/godot_ai/resources/` — read-only `godot://...` URI handlers
- `src/godot_ai/middleware/` — `PreserveGodotCommandErrorData`, `StripClientWrapperKwargs`, `ParseStringifiedParams`, `HintOpTypoOnManage` (registration order is load-bearing — see `server.py` docstring + `tests/unit/test_server_middleware_order.py`)
- `src/godot_ai/protocol/` — envelope types and error codes (kept in sync with `utils/error_codes.gd`)
```

--------------------------------

### Run Basic Stress Test

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Initiate a stress test using stormtest.py, which opens numerous concurrent MCP clients and sends rapid, randomized tool calls to a live editor. This test is designed to check for crashes and stability issues under heavy load.

```bash
.venv/bin/python script/stormtest.py                       # ≈ 1000 calls, with reload churn
```

--------------------------------

### Build Binary with PyInstaller

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/packaging-distribution.md

Command to build a standalone binary for the Godot AI project using PyInstaller. This command bundles the application and its dependencies into a single executable file.

```bash
pyinstaller --onefile \
    --name godot-ai \
    --add-data "src/godot_ai:godot_ai" \
    src/godot_ai/__main__.py
```

--------------------------------

### Serve Worktree with Reload

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/STRESS_TESTING.md

Launches a Python server for a specific worktree, enabling `--reload` and matching editor ports. This ensures the server reflects your current worktree code.

```bash
python script/serve_worktree.py --port 8000 --ws-port 9500
```

--------------------------------

### Launch Godot Editor - Safe Root Repo

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

This command launches the Godot editor using the `test_project` located in the root repository. This path is safe as it is never auto-cleaned.

```bash
/Applications/Godot_mono.app/Contents/MacOS/Godot --editor --path ~/godot-ai/test_project/
```

--------------------------------

### Plugin File Structure Overview

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/plugin-architecture.md

Provides a hierarchical view of the plugin's directory and file organization. This structure helps in understanding the placement and purpose of various modules within the plugin.

```text
plugin/addons/godot_ai/
├── plugin.cfg
├── plugin.gd                    ## EditorPlugin lifecycle, handler registration
├── connection.gd                ## WebSocket client + send_deferred_response
├── dispatcher.gd                ## command routing, frame budget, DEFERRED_RESPONSE sentinel
├── mcp_dock.gd                  ## editor dock: status, clients, logs, self-update banner, Tools tab
├── client_configurator.gd       ## thin facade for client config (configure/remove/status)
├── tool_catalog.gd              ## mirrors src/godot_ai/tools/domains.py; CI-enforced
├── update_reload_runner.gd      ## self-update single-pass extract, scan, and re-enable handoff
├── handlers/                    ## one file per domain; ~30 handlers
│   ├── editor_handler.gd        ## screenshot, logs, monitors, reload_plugin, quit_editor
│   ├── scene_handler.gd, node_handler.gd, script_handler.gd
│   ├── project_handler.gd, resource_handler.gd, filesystem_handler.gd
│   ├── animation_handler.gd, material_handler.gd, particle_handler.gd
│   ├── camera_handler.gd, audio_handler.gd, theme_handler.gd, ui_handler.gd
│   ├── signal_handler.gd, autoload_handler.gd, input_handler.gd
│   ├── batch_handler.gd, test_handler.gd, client_handler.gd
│   ├── environment_handler.gd, texture_handler.gd, curve_handler.gd
│   ├── physics_shape_handler.gd, control_draw_recipe_handler.gd
│   ├── *_values.gd / *_presets.gd  ## per-domain enum coercion + preset libraries
│   └── _param_validators.gd, _property_errors.gd  ## shared utilities (Mcp* class_name)
├── clients/                     ## descriptor + strategy system for 18 IDE configs
│   ├── _base.gd, _registry.gd
│   ├── _json_strategy.gd, _toml_strategy.gd, _cli_strategy.gd
│   ├── _atomic_write.gd, _cli_finder.gd, _cli_exec.gd
│   ├── _path_template.gd, _manual_command.gd
│   └── claude_code.gd, claude_desktop.gd, cursor.gd, …  ## one per client
├── debugger/
│   └── mcp_debugger_plugin.gd   ## editor-side debugger-channel bridge
├── runtime/
│   ├── game_helper.gd           ## autoload that runs inside the game subprocess
│   ├── editor_logger.gd         ## Logger-backed editor diagnostics capture
│   ├── game_logger.gd           ## Logger-backed game log bridge
│   ├── validation_logger.gd     ## short-lived Logger for script-write diagnostics
│   └── draw_recipe.gd           ## reusable runtime for control_draw_recipe
├── testing/
│   ├── test_runner.gd, test_suite.gd, stub_backtrace.gd
└── utils/
    ├── scene_path.gd            ## McpScenePath for clean /Main/Camera3D paths
    ├── error_codes.gd           ## McpErrorCodes
    ├── log_buffer.gd, editor_log_buffer.gd, game_log_buffer.gd, structured_log_ring.gd
    ├── log_backtrace.gd
    ├── resource_io.gd           ## shared resource load/save logic
    ├── mcp_spawn_state.gd       ## tracks managed-server PID + version across reloads
    ├── windows_port_reservation.gd  ## avoids Windows-reserved ephemeral ports
    └── uv_cache_cleanup.gd      ## prunes stale uvx cache before self-update
```

--------------------------------

### Registering a Named Tool with MCP

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Use this for high-traffic verbs. Register the tool with `@mcp.tool(meta=DEFER_META)` and ensure the last parameter is `session_id: str`. Pass the session ID using `DirectRuntime.from_context(ctx, session_id=session_id or None)`.

```python
from godot_ai.tools import DEFER_META

@mcp.tool(meta=DEFER_META)
def my_high_traffic_tool(param1: str, session_id: str = ""):
    runtime = DirectRuntime.from_context(ctx, session_id=session_id or None)
    # ... tool logic
```

--------------------------------

### Adding Resource Forms for Read Tools

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Pure read tools without `session_id` filtering can benefit from a matching `godot://...` resource in `src/godot_ai/resources/`. Append 'Resource form: godot://...' to the tool's description.

```gdscript
# Example: Add 'Resource form: godot://my_resource_template' to the tool's description.
```

--------------------------------

### Run Godot AI Server with Remote Access

Source: https://github.com/hi-godot/godot-ai/blob/main/README.md

Launches the Godot AI MCP server, allowing connections from other machines on the network. Specify allowed hosts using CIDR notation or IP addresses.

```bash
godot-ai --allow-host 192.168.1.0/24
```

--------------------------------

### Verify and Repair Worktree Link

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

This bash script checks for the existence and integrity of the `plugin.gd` file and the symlink/directory junction for `test_project/addons/godot_ai`. It automatically creates or repairs these if they are missing or broken, requiring no admin rights or developer mode.

```bash
script/verify-worktree
```

--------------------------------

### Launch Godot Editor - Dangerous Other Worktree

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

This command launches the Godot editor using a `test_project` from another session's worktree. This is dangerous as these worktrees can be auto-removed, leading to permanent data loss for uncommitted files.

```bash
/Applications/Godot_mono.app/Contents/MacOS/Godot --editor --path .claude/worktrees/some-other-name/test_project/
```

--------------------------------

### Configure uvx-bridge Client with UV_LINK_MODE

Source: https://github.com/hi-godot/godot-ai/blob/main/README.md

This JSON configuration snippet is used to set the UV_LINK_MODE environment variable to 'copy' for uvx-bridge clients. This helps resolve issues with shared C extensions on Windows by preventing hard-linking conflicts.

```json
{
  "mcpServers": {
    "godot-ai": {
      "command": "uvx",
      "args": ["mcp-proxy==0.11.0", "--transport", "streamablehttp", "http://127.0.0.1:8000/mcp"],
      "env": { "UV_LINK_MODE": "copy" }
    }
  }
}
```

--------------------------------

### Run Python Tests and Linting

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/CONTRIBUTING.md

Execute unit and integration tests using pytest, and check code quality with ruff for linting and formatting.

```bash
pytest -v                    # unit + integration tests
```

```bash
ruff check src/ tests/       # lint
```

```bash
ruff format src/ tests/      # format
```

--------------------------------

### Godot AI Architecture Overview

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Illustrates the flow of communication from an AI client through the MCP and Python server to the Godot EditorPlugin.

```text
AI Client → MCP (stdio/sse/streamable-http) → Python FastMCP server → WebSocket (port 9500) → Godot EditorPlugin
```

--------------------------------

### Create Addon Directory Junction (Windows)

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Commands to create a directory junction for the Godot AI addon on Windows. This is used to link the plugin to the Godot project without requiring admin rights or Developer Mode.

```powershell
# from repo root or worktree root
Remove-Item -LiteralPath test_project\addons\godot_ai -Force -ErrorAction SilentlyContinue
New-Item -ItemType Junction -Path test_project\addons\godot_ai -Target ..\..\plugin\addons\godot_ai
```

```cmd
mklink /J test_project\addons\godot_ai ..\..\plugin\addons\godot_ai
```

--------------------------------

### Godot AI Plugin Concurrency Flow

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/plugin-architecture.md

Illustrates the receive path for WebSocket commands, emphasizing queuing and processing within the main thread's _process() method to avoid blocking editor APIs.

```text
WebSocket receive
       │
       ▼
command_queue append
       │
       ▼
_process(delta)
       │
       ├─ poll WebSocket
       ├─ drain queue within frame budget
       ├─ dispatch editor work
       └─ send responses
```

--------------------------------

### Run Godot-side Test Suites

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Execute test suites within the Godot editor using the MCP (Message Communication Protocol). Options include running a specific suite or enabling verbose output.

```bash
test_run                     # compact: summary + failures only
```

```bash
test_run suite=scene         # run one suite
```

```bash
test_run verbose=true        # include every individual test result
```

```bash
test_results_get             # review last results
```

--------------------------------

### Run Interactive Self-Update Smoke Test

Source: https://github.com/hi-godot/godot-ai/blob/main/docs/testing-strategy.md

Execute the local self-update smoke test harness. This prepares a project, builds a synthetic release, forces an update, and monitors for stability and errors during the process.

```bash
script/local-self-update-smoke
```

--------------------------------

### Clone Godot AI Plugin from Source

Source: https://github.com/hi-godot/godot-ai/blob/main/README.md

Use this command to clone the latest version of the Godot AI plugin directly from its GitHub repository.

```bash
git clone https://github.com/hi-godot/godot-ai.git
cp -r godot-ai/plugin/addons/godot_ai your-project/addons/
```

--------------------------------

### Configure Antigravity MCP Server

Source: https://github.com/hi-godot/godot-ai/blob/main/README.md

Manually configure Antigravity to connect to the Godot AI MCP server by editing its JSON configuration file.

```json
{
  "mcpServers": {
    "godot-ai": {
      "serverUrl": "http://127.0.0.1:8000/mcp",
      "disabled": false
    }
  }
}
```

--------------------------------

### Run Python Unit and Integration Tests

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

Execute all unit and integration tests using pytest. This command runs a comprehensive suite of tests for the project.

```bash
pytest -v                    # 903 unit + integration tests
```

--------------------------------

### Launch Godot Editor - Safe Current Worktree

Source: https://github.com/hi-godot/godot-ai/blob/main/AGENTS.md

This command launches the Godot editor using the `test_project` within the current session's worktree. It is safe to use if you frequently commit your changes, as this worktree can be auto-removed when the session exits.

```bash
/Applications/Godot_mono.app/Contents/MacOS/Godot --editor --path .claude/worktrees/<this-session>/test_project/
```