Godot LSP Bridge
┌──────────────────────────────────────────────┐
│ G O D O T L S P B R I D G E │
│ GDScript intelligence for Claude Code │
└──────────────────────────────────────────────┘
Full GDScript code intelligence — go-to-definition, hover docs, completions, diagnostics, and GDShader validation — inside Claude Code, powered by Godot's native Language Server.
Supported Godot Versions
Godot 4.x (4.0 and later). The LSP server runs on port 6005 automatically when the Godot editor is open with a project loaded.
Quick Start
Step 1 — Install the binary
Linux / macOS (recommended):
curl -fsSL https://raw.githubusercontent.com/Pixel-Directive-LLC/godot-lsp-bridge/main/install.sh | bash
Windows (PowerShell):
irm https://raw.githubusercontent.com/Pixel-Directive-LLC/godot-lsp-bridge/main/install.ps1 | iex
Rust developers — install via cargo-binstall (downloads pre-built binary, no compile):
cargo binstall godot-lsp-bridge
Step 2 — Register the Claude Code plugin
/plugin marketplace add https://github.com/Pixel-Directive-LLC/godot-lsp-bridge.git
/plugin install godot-lsp-bridge@godot-lsp-bridge
That's it. Open Godot with a project, open any .gd file in Claude Code, and GDScript intelligence is live.
Manual registration (fallback): if the marketplace commands are unavailable, add the entry directly to ~/.claude/settings.json:
{
"lsp": {
"godot-lsp-bridge": {
"transport": "stdio",
"command": "godot-lsp-bridge",
"args": []
}
}
}
Features
- Full GDScript intelligence — go-to-definition, hover docs, completions, and diagnostics powered by Godot's native LSP
- GDShader diagnostics — validates
.gdshader files by running Godot headless, surfacing shader compilation errors as LSP diagnostics with line-accurate ranges
- Auto-discovery — scans ports 6005–6014 and connects to the running Godot instance automatically
- Retry on startup — exponential-backoff probe when Godot hasn't launched yet; no manual restarts needed
- Hot-reconnect — detects in-session project switches and reconnects without restarting Claude Code
- Reliable framing —
Content-Length JSON-RPC framing prevents message truncation on high-latency connections
- Zero dependencies at runtime — single statically-linked binary; no Node, Python, or JVM required
- Cross-platform — native binaries for Windows, macOS, and Linux
CLI Reference
Proxy flags
All flags below are stable as of v1.0. Shader flags added in v1.3.
| Flag | Default | Description |
|---|
--version | — | Print version and exit |
--host <ADDR> | 127.0.0.1 | Godot LSP host |
--port <N> | (auto-detect) | Skip discovery; connect to explicit port |
--connect-timeout <SECS> | 300 | Max wait time for Godot to appear |
--godot-path <PATH> | (auto-detect) | Path to the Godot binary for shader validation |
--shader-timeout <SECS> | 10 | Timeout for the Godot shader validation subprocess |
--log-level <LEVEL> | info | Tracing level (error/warn/info/debug/trace) |
Resolution order for --host, --port, and --godot-path: CLI flag → config file → built-in default (PATH lookup for Godot).
The RUST_LOG environment variable is also honoured (tracing-subscriber env-filter).
# Print the installed version
godot-lsp-bridge --version
# Auto-discover Godot on ports 6005–6014 (Godot editor must be open)
godot-lsp-bridge
# Connect to an explicit port (skips auto-discovery)
godot-lsp-bridge --port 6005
# Wait up to 10 minutes for Godot to start
godot-lsp-bridge --connect-timeout 600
Subcommands
update
Download and install the latest release, then ensure the install directory is on PATH.
godot-lsp-bridge update
- Fetches release metadata from GitHub, downloads the platform-appropriate archive, and atomically replaces the running binary.
- If the install directory is not already on
PATH, it is added automatically (shell rc file on Linux/macOS; User PATH via PowerShell on Windows).
doctor
Check the environment and report diagnostics. Exits with code 1 if any check fails.
godot-lsp-bridge doctor
Checks:
- Binary in PATH — confirms
godot-lsp-bridge is reachable from the shell.
- Godot LSP reachable — probes the configured
host:port with a 2-second TCP timeout.
Host and port are resolved using the same priority as proxy mode (CLI flag → config file → built-in default). Unlike proxy mode, doctor does not perform auto-discovery and defaults to port 6005. Pass --host or --port to test a non-default target:
godot-lsp-bridge --port 6007 doctor
config
Read or write persistent host/port defaults. Settings are stored in a JSON file under the platform config directory: