{"id":50753417,"url":"https://github.com/kurushimee/gdls","last_synced_at":"2026-06-11T03:02:37.533Z","repository":{"id":363119156,"uuid":"1261629517","full_name":"kurushimee/gdls","owner":"kurushimee","description":"Standalone, type-aware GDScript language server: a faithful Rust port of Godot 4.6.3-stable's GDScript frontend — LSP over stdio, no Godot process at runtime.","archived":false,"fork":false,"pushed_at":"2026-06-07T14:06:49.000Z","size":823,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T15:20:31.905Z","etag":null,"topics":["developer-tools","gdscript","godot","godot4","language-server","lsp","parser","rust","static-analysis","type-checker"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kurushimee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T00:21:05.000Z","updated_at":"2026-06-07T14:06:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kurushimee/gdls","commit_stats":null,"previous_names":["kurushimee/gdls"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kurushimee/gdls","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurushimee%2Fgdls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurushimee%2Fgdls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurushimee%2Fgdls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurushimee%2Fgdls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kurushimee","download_url":"https://codeload.github.com/kurushimee/gdls/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kurushimee%2Fgdls/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34180147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","gdscript","godot","godot4","language-server","lsp","parser","rust","static-analysis","type-checker"],"created_at":"2026-06-11T03:02:36.802Z","updated_at":"2026-06-11T03:02:37.528Z","avatar_url":"https://github.com/kurushimee.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gdls — a standalone GDScript language server for Godot 4.6.3-stable\n\n[![CI](https://github.com/kurushimee/gdls/actions/workflows/ci.yml/badge.svg)](https://github.com/kurushimee/gdls/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-stable-dea584.svg?logo=rust)](rust-toolchain.toml)\n[![Godot conformance](https://img.shields.io/badge/Godot%20conformance-1.0000-brightgreen.svg)](docs/06-testing-fidelity.md)\n\nA single self-contained language server providing **type-aware GDScript diagnostics and\nnavigation** to Claude Code (and any LSP client) over stdio — **with no Godot engine or editor\nprocess running at runtime**.\n\n`gdls` is a faithful Rust port of the GDScript frontend (tokenizer → parser → analyzer) of\nGodot 4.6.3-stable. It exists to fix the editor LSP's weight, staleness, and engine coupling at\nthe 3,000–10,000+ `.gd` scale. Only the frontend is ported — the compiler/bytecode/VM half is out\nof scope (diagnostics only).\n\n## Install\n\n`gdls` is not shipped by Claude Code; you grab a release binary (or build one) and put it on `PATH`.\n\n- **Prebuilt binaries** — download `gdls` (Linux x86_64) or `gdls.exe` (Windows x86_64) from\n  [GitHub Releases](https://github.com/kurushimee/gdls/releases).\n\n- **From source (cargo)** — builds straight from this repo and installs the `gdls` binary into\n  `~/.cargo/bin` (no checkout needed):\n\n  ```sh\n  cargo install --git https://github.com/kurushimee/gdls gd_server\n  ```\n\nThe toolchain is pinned by `rust-toolchain.toml` (stable).\n\n`gdls` speaks JSON-RPC over **stdio**, so a bare `gdls` invocation just waits for an LSP client on\nstdin. To smoke-test the binary without wiring up a client, point its index pass at a project — it\nexits cleanly and prints a reconcile summary to stderr:\n\n```sh\ngdls diagnose --reconcile --root /path/to/your/godot/project\n```\n\n## Quick start\n\n1. **Register the server** with your LSP client. For Claude Code, install the official plugin\n   from the [`kurushimee/gdls-plugin`](https://github.com/kurushimee/gdls-plugin) marketplace —\n   inside a Claude Code session:\n\n   ```\n   /plugin marketplace add kurushimee/gdls-plugin\n   /plugin install gdls@gdls-plugin\n   ```\n\n   For any other LSP client (or a hand-rolled plugin), the core registration is five lines:\n\n   ```json\n   {\n     \"gdscript\": {\n       \"command\": \"gdls\",\n       \"extensionToLanguage\": { \".gd\": \"gdscript\" }\n     }\n   }\n   ```\n\n2. **Native types: nothing to do** (since v1.0.1). gdls finds your Godot binary\n   (`godotBinaryPath` option → `GDLS_GODOT` env → `godot4`/`godot` on PATH), runs\n   `--dump-extension-api-with-docs` with project context — which is what captures the project's\n   GDExtension classes — and manages the result under `.gdls/`, regenerating only when the\n   binary or the project's `.gdextension` set changes. Since v1.0.2 the dump runs in the\n   background (it never delays a request; the session re-checks open files the moment it lands),\n   and when no binary is discoverable at all, a bundled stock 4.6.3 class surface keeps builtins\n   (`Node`, `Timer`, …) resolving — without inventing \"unknown type\" errors for classes only\n   your engine build knows. To pin a hand-made dump instead, set\n   `initializationOptions.extensionApiPath`; to forbid gdls from ever spawning Godot, set\n   `autoDumpExtensionApi: false` (or `GDLS_GODOT=off`) and dump manually from inside the\n   project directory:\n\n   ```sh\n   godot --dump-extension-api-with-docs\n   ```\n\n   Details and the multi-source capture story (incl. `doc_classes` XML fallback) are in\n   [`docs/03-indexing-freshness.md`](docs/03-indexing-freshness.md) §1–§2.\n\n## Configuration\n\nThe server is configured entirely through LSP `initializationOptions` —\n`projectRoot`, the auto-dump pair (`godotBinaryPath`, `autoDumpExtensionApi`),\n`extensionApiPath` to pin a manual dump, and the `strict` diagnostics profile\n(`godot` / `strict` / `off`) plus per-warning overrides. The full schema and a worked manifest are\nin [`docs/05-lsp-cc-integration.md`](docs/05-lsp-cc-integration.md) §3.\n\n## Architecture\n\n- **Problem, goal, and locked decisions** — [`docs/00-overview.md`](docs/00-overview.md).\n- **Components, control loops, and the crate DAG** (`gd_syntax` → `gd_types` →\n  `gd_analyze` / `gd_project` → `gd_server`) — [`docs/01-architecture.md`](docs/01-architecture.md).\n\n## Status\n\n**Phase 1 = M0–M6 = v1. Complete.** Both fidelity ratchets are at **1.0000** (parser 186/186, analyzer\n300/300) against the vendored Godot 4.6.3-stable conformance corpus. **M6** closed the exposed-capability\nparity gaps vs Godot's own LSP (hover member signatures, `definition`/`documentLink` on\n`class_name`/`preload`/autoloads, project-wide `references`, hierarchical `documentSymbol`,\n`implementation` overrides, autoload-singleton typing) and added a persistent, multi-instance-safe\nwarm-start index cache (a warm relaunch is **\u003e5×** faster than a cold scan). Verified by capability\nwalks against a real Godot 4.6.3 OSS project and a Windows-native 2,338-script production project.\n**v1.0.3** is the current release — the warning-completeness release: the full Godot warning set\nnow actually fires (19 previously-declared-but-silent codes ported function-for-function, from\n`UNREACHABLE_CODE` and `STANDALONE_EXPRESSION` to `UNASSIGNED_VARIABLE` and `INTEGER_DIVISION`),\n`@warning_ignore` suppresses across multi-line targets exactly like Godot's annotation→target\nspans, and a real-project walk of every exposed capability fixed cross-file `definition` on\ndotted method calls, cross-file `incomingCalls`, call-site `prepareCallHierarchy`, and the last\n`\u003cScript #N\u003e` placeholder leak. Before it, **v1.0.2** made the first run robust (background\n`extension_api.json` auto-dump adopted mid-session, embedded stock 4.6.3 fallback with\nprovenance-gated negative diagnostics) and **v1.0.1** fixed the cross-file false-positive\nfamilies a full-project diagnostics sweep exposed right after v1.0.0.\nSee [`docs/08-m6-v1-ship.md`](docs/08-m6-v1-ship.md) for the M6 scope and\n[`CHANGELOG.md`](CHANGELOG.md) for the milestone history.\n\nPhase 2 (post-v1): `.tscn` node typing for `$`/`%`, `signatureHelp`, `completion`, and `rename` /\n`documentHighlight`. (The persistent warm-start index cache was pulled forward into **M6** — it now\ngates v1.) Roadmap in [`docs/07-milestones-risks.md`](docs/07-milestones-risks.md).\n\n## Contributing\n\nContributions are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). The one thing to read first is the\n*faithful-port discipline*: `gdls` mirrors Godot's frontend function-for-function and matches its\ndiagnostics byte-for-byte, so fidelity to the upstream source is reviewed ahead of Rust idiom. The dev\nloop is the CI gate (`cargo fmt --all --check`, `cargo lint`, `cargo build`, `cargo test`).\n\n## License\n\n`gdls` is released under the [MIT License](LICENSE).\n\nIt is a faithful port of the GDScript frontend of [Godot Engine](https://github.com/godotengine/godot),\nwhich is also MIT-licensed; substantial portions of this software are derived from Godot's source, and the\nGodot Engine copyright notice is retained in [`LICENSE`](LICENSE) as that license requires.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurushimee%2Fgdls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkurushimee%2Fgdls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkurushimee%2Fgdls/lists"}