litclaude-ai 0.3.3 → 0.3.6

package/plugins/litclaude/skills/lsp-setup/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: lsp-setup
+description: "Configure a Language Server (LSP) for a specific language so Claude Code tooling — diagnostics, go-to-definition, find-references, rename — works in LitClaude. Use when you need to set up or install a language server, fix 'no LSP server configured' / 'server not installed', choose between servers (basedpyright vs pyright vs ruff), or add a language to plugins/litclaude/.lsp.json. Routes by file extension to references/<language>/README.md for the server choice, per-OS install commands, the .lsp.json config snippet, and troubleshooting. Ships scripts: detect-lsp.ts (scan a project for languages + report each server's install/config status against .lsp.json) and verify-lsp.ts (real diagnostics roundtrip). Covers typescript, python, go, rust, c/c++, java, kotlin, c#/razor, swift, ruby, php, dart, elixir, zig, lua, bash, yaml, terraform, haskell, julia."
+---
+
+# LSP Setup
+
+Configure the right Language Server for a project so Claude Code's LSP tools
+(`diagnostics`, `goto_definition`, `find_references`, `symbols`, `rename`)
+actually work in LitClaude. This skill is an index: detect what a project needs,
+install the server, declare it in `plugins/litclaude/.lsp.json`, then verify with
+a real diagnostics roundtrip.
+
+This is the multi-language configurator. For a quick post-edit diagnostics pass
+on an already-configured language, use the lighter `lsp` skill instead — `lsp` is
+the quick path, `lsp-setup` is the configurator that wires new languages in.
+
+The recommended server per language is the source of truth in
+`scripts/lsp-server-table.ts`; each `references/<language>/README.md` mirrors it.
+
+## Runtime
+
+The scripts are dependency-free TypeScript. Run them with either:
+
+- **Node 22.6+:** `node --experimental-strip-types scripts/detect-lsp.ts <dir>`
+- **Bun:** `bun scripts/detect-lsp.ts <dir>`
+
+No `npm install` is required; the scripts import only Node built-ins and the
+embedded `lsp-server-table.ts`.
+
+## Phase 0 — Language Gate (run first)
+
+Identify the language from the file extension, then read the matching reference
+before installing or configuring anything.
+
+| Extension(s) | Reference |
+|---|---|
+| `.ts .tsx .js .jsx .mjs .cjs .mts .cts` | `references/typescript/README.md` |
+| `.py .pyi` | `references/python/README.md` |
+| `.go` | `references/go/README.md` |
+| `.rs` | `references/rust/README.md` |
+| `.c .cpp .cc .cxx .h .hpp .hh .hxx` | `references/c-cpp/README.md` |
+| `.java` | `references/java/README.md` |
+| `.kt .kts` | `references/kotlin/README.md` |
+| `.cs .razor .cshtml` | `references/csharp/README.md` |
+| `.swift` | `references/swift/README.md` |
+| `.rb .rake .gemspec .ru` | `references/ruby/README.md` |
+| `.php` | `references/php/README.md` |
+| `.dart` | `references/dart/README.md` |
+| `.ex .exs` | `references/elixir/README.md` |
+| `.zig .zon` | `references/zig/README.md` |
+| `.lua` | `references/lua/README.md` |
+| `.sh .bash .zsh .ksh` | `references/bash/README.md` |
+| `.yaml .yml` | `references/yaml/README.md` |
+| `.tf .tfvars` | `references/terraform/README.md` |
+| `.hs .lhs` | `references/haskell/README.md` |
+| `.jl` | `references/julia/README.md` |
+
+## Workflow — detect, install, configure, verify
+
+### 1. Detect
+
+Scan the project to see which languages are present and whether each server is
+installed and already declared in `.lsp.json`:
+
+```bash
+node --experimental-strip-types scripts/detect-lsp.ts <projectDir>
+node --experimental-strip-types scripts/detect-lsp.ts <projectDir> --json
+```
+
+For each detected language it prints the recommended server, the executable it
+needs on `PATH`, whether that executable is installed, an install hint, and
+whether `plugins/litclaude/.lsp.json` already declares the language. Use
+`--config=<path>` to point at a different `.lsp.json` copy.
+
+### 2. Install
+
+Open `references/<language>/README.md` and run the install command for your OS,
+then confirm the executable resolves:
+
+```bash
+command -v <server-executable>   # e.g. typescript-language-server, gopls, rust-analyzer
+```
+
+### 3. Configure (LitClaude `.lsp.json`)
+
+LitClaude declares servers in `plugins/litclaude/.lsp.json`. The schema is keyed
+by **language name**; each entry holds a `command` array and an
+`extensionToLanguage` map that tells Claude Code which file extensions route to
+that server:
+
+```json
+{
+  "<language>": {
+    "command": ["<bin>", "<arg>"],
+    "extensionToLanguage": {
+      ".ext": "<languageId>"
+    }
+  }
+}
+```
+
+Rules:
+
+- One entry per server, keyed by language name. The `command` is the full argv.
+- `extensionToLanguage` maps each owned extension to the LSP `languageId`. Claude
+  Code resolves the server for an edited file by matching its extension here.
+- The shipped default declares only `typescript`. Add a language by copying the
+  block from its reference README into `.lsp.json`.
+- Server-specific tuning (schemas, licence keys, check commands) travels through
+  the editor's LSP `initializationOptions` or a project config file (for example
+  `.clangd`, `.rubocop.yml`, `pyrightconfig.json`), not through `.lsp.json`.
+
+If a language also needs an MCP wiring (for example a server exposed through an
+MCP stdio bridge rather than a direct binary), declare that bridge in `.mcp.json`
+and keep `.lsp.json` pointed at the resulting command. Most servers here are
+direct binaries and need only `.lsp.json`.
+
+Each language reference gives a ready-to-paste `.lsp.json` snippet.
+
+### 4. Verify
+
+Run a real diagnostics roundtrip against a source file. The script resolves the
+server for the file extension (from `.lsp.json` when present, else the embedded
+table), spawns it, runs the JSON-RPC `initialize` -> `initialized` -> `didOpen`
+handshake over stdio, waits for `textDocument/publishDiagnostics`, and reports:
+
+```bash
+node --experimental-strip-types scripts/verify-lsp.ts <path/to/file.ext>
+node --experimental-strip-types scripts/verify-lsp.ts <file> --timeout=90000
+```
+
+`OK` = the server started and answered with diagnostics. `FAIL: language server
+not installed` = go back to step 2. Other `FAIL` text carries the server or
+timeout error. `SKIP` = no server is known for that extension; add one via the
+reference and `.lsp.json`. Exit codes: 0 OK, 1 FAIL, 2 usage, 3 SKIP.
+
+## Scripts
+
+| Script | Purpose |
+|---|---|
+| `scripts/detect-lsp.ts` | Scan a directory; per detected language report the recommended server, install status, install hint, and whether `.lsp.json` declares it. `--json` for machine output, `--config=<path>` to target a config. |
+| `scripts/verify-lsp.ts` | Real LSP diagnostics roundtrip for one file over stdio JSON-RPC; `OK`/`FAIL`/`SKIP` + exit code 0/1/2/3. Dependency-free. |
+| `scripts/lsp-server-table.ts` | Embedded snapshot of the recommended server per language, mirrored by the references. |
+
+## When LSP tooling is unavailable
+
+If Claude Code does not expose LSP tools and a server is not installed, do not
+fabricate a passing diagnostics result. Fall back to the project's own commands
+(`tsc --noEmit`, `ruff`, `cargo check`, `go test`, etc.), label the LSP gap as a
+controlled skip, and report it — consistent with the `lsp` skill's failure rules.

package/plugins/litclaude/skills/lsp-setup/references/bash/README.md

@@ -0,0 +1,63 @@
+# Bash — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `bash-language-server start`
+- **Extensions:** `.sh .bash .zsh .ksh`
+- **Install hint:** `npm install -g bash-language-server`
+
+## Install
+
+- **macOS:** `npm install -g bash-language-server`
+- **Linux:** `npm install -g bash-language-server`
+- **Windows:** `npm install -g bash-language-server` (PowerShell)
+
+For real diagnostics, also install `shellcheck`:
+
+- **macOS:** `brew install shellcheck`
+- **Linux:** `apt install shellcheck` (or `dnf install ShellCheck`)
+- **Windows:** `scoop install shellcheck`
+
+Confirm it resolves:
+
+```bash
+command -v bash-language-server
+command -v shellcheck
+```
+
+## Configure
+
+Add a `bash` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "bash": {
+    "command": ["bash-language-server", "start"],
+    "extensionToLanguage": {
+      ".sh": "shellscript",
+      ".bash": "shellscript",
+      ".zsh": "shellscript",
+      ".ksh": "shellscript"
+    }
+  }
+}
+```
+
+Claude Code routes these extensions to `bash-language-server` via the map.
+`bash-language-server` discovers `shellcheck` on PATH automatically; to point at a
+non-PATH binary, export `SHELLCHECK_PATH` in the launching shell.
+
+## Alternatives
+
+- `shellcheck` standalone as a linter-only flow (no LSP).
+- `shfmt` for formatting (complements, does not replace, the LSP).
+
+## Troubleshooting
+- **PATH:** `bash-language-server` on PATH; reopen shell after `npm -g` install.
+- **No diagnostics:** `shellcheck` missing — diagnostics are powered by it; install and reopen.
+- **Wrong shell dialect:** `.zsh`/`.ksh` are linted as bash; shellcheck may flag shell-specific syntax.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.sh
+# or: bun ../../scripts/verify-lsp.ts path/to/file.sh
+```

package/plugins/litclaude/skills/lsp-setup/references/c-cpp/README.md

@@ -0,0 +1,72 @@
+# C / C++ — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `clangd --background-index --clang-tidy`
+- **Extensions:** `.c .cpp .cc .cxx .c++ .h .hpp .hh .hxx .h++`
+- **Install hint:** `https://clangd.llvm.org/installation`
+
+## Install
+
+- **macOS:** `brew install llvm` (clangd ships in the LLVM keg; add its `bin` to PATH)
+- **Linux:** `apt install clangd` (Debian/Ubuntu); use your distro package elsewhere
+- **Windows:** install LLVM from `https://releases.llvm.org` or `winget install LLVM.LLVM`
+
+See `https://clangd.llvm.org/installation` for other platforms.
+
+Confirm it resolves:
+
+```bash
+command -v clangd
+```
+
+## Configure
+
+Add a `c-cpp` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "c-cpp": {
+    "command": ["clangd", "--background-index", "--clang-tidy"],
+    "extensionToLanguage": {
+      ".c": "c",
+      ".h": "c",
+      ".cpp": "cpp",
+      ".cc": "cpp",
+      ".cxx": "cpp",
+      ".hpp": "cpp",
+      ".hh": "cpp",
+      ".hxx": "cpp"
+    }
+  }
+}
+```
+
+Claude Code routes these extensions to `clangd` via the map. clangd reads
+build flags from a project `.clangd` file, not from `.lsp.json`; the `command`
+above already passes `--background-index --clang-tidy`.
+
+## Compile commands
+
+clangd needs a `compile_commands.json` at the project root (or in `build/`) for
+accurate diagnostics and cross-file navigation. Generate it with:
+
+- **CMake:** `cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON` (symlink/copy `build/compile_commands.json` to the root)
+- **Make / other:** `bear -- make`
+
+Without it, clangd falls back to heuristic flags and reports spurious errors.
+
+## Alternatives
+
+`ccls` exists as a third-party server — set the `command` to `["ccls"]` in the
+`c-cpp` entry if you prefer it.
+
+## Troubleshooting
+- **PATH:** `clangd` must be on PATH; reopen shell after install. Homebrew LLVM is keg-only — add `$(brew --prefix llvm)/bin` to PATH.
+- **Spurious "file not found" / unknown flags:** missing or stale `compile_commands.json` — regenerate it after changing the build.
+- **Header-only diagnostics wrong:** ensure the header's translation unit appears in the compile database, or add a `.clangd` `CompileFlags` block.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.cpp
+# or: bun ../../scripts/verify-lsp.ts path/to/file.cpp
+```

package/plugins/litclaude/skills/lsp-setup/references/csharp/README.md

@@ -0,0 +1,81 @@
+# C# — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `csharp-ls`
+- **Extensions:** `.cs`
+- **Install hint:** `dotnet tool install -g csharp-ls`
+
+## Install
+
+Requires the **.NET SDK**. Install the tool globally:
+
+- **macOS:** `dotnet tool install -g csharp-ls`
+- **Linux:** `dotnet tool install -g csharp-ls`
+- **Windows:** `dotnet tool install -g csharp-ls`
+
+Global .NET tools land in `~/.dotnet/tools` — ensure that directory is on PATH (Windows: `%USERPROFILE%\.dotnet\tools`).
+
+Confirm it resolves:
+
+```bash
+command -v csharp-ls
+```
+
+## Configure
+
+Add a `csharp` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "csharp": {
+    "command": ["csharp-ls"],
+    "extensionToLanguage": {
+      ".cs": "csharp"
+    }
+  }
+}
+```
+
+Claude Code routes `.cs` edits to `csharp-ls` via the map. `csharp-ls` picks up
+the nearest `.sln` or `.csproj`; keep the solution restorable (`dotnet restore`).
+
+## Razor / Blazor
+
+Razor and Blazor files use a separate server. Add a second entry:
+
+```json
+{
+  "razor": {
+    "command": ["roslyn-language-server", "--stdio"],
+    "extensionToLanguage": {
+      ".razor": "razor",
+      ".cshtml": "razor"
+    }
+  }
+}
+```
+
+Install it (requires **v5.8.0+**; see [dotnet/razor](https://github.com/dotnet/razor)):
+
+```bash
+dotnet tool install -g roslyn-language-server --prerelease
+command -v roslyn-language-server
+```
+
+## Alternatives
+
+**OmniSharp** — legacy C# language server. Still works but is being superseded by
+the Roslyn-based servers; prefer `csharp-ls` / `roslyn-language-server`.
+
+## Troubleshooting
+
+- **PATH:** `csharp-ls` / `roslyn-language-server` on PATH (`~/.dotnet/tools`); reopen shell after install.
+- **No .NET SDK:** install the SDK (not just the runtime) before installing the tool.
+- **No symbols:** run `dotnet restore`; an unrestored solution yields empty results.
+- **Razor needs v5.8.0+:** older `roslyn-language-server` builds lack the `--stdio` Razor support — install with `--prerelease`.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/File.cs
+# or: bun ../../scripts/verify-lsp.ts path/to/File.cs
+```

package/plugins/litclaude/skills/lsp-setup/references/dart/README.md

@@ -0,0 +1,53 @@
+# Dart — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `dart language-server --lsp`
+- **Extensions:** `.dart`
+- **Install hint:** `Included with the Dart/Flutter SDK`
+
+## Install
+
+The language server ships inside the Dart SDK (and the Flutter SDK, which bundles Dart). There is no separate package to install — just put `dart` (or `flutter`) on PATH.
+
+- **macOS:** `brew install dart` (or install Flutter and use its bundled `dart`)
+- **Linux:** install the Dart SDK from your package manager / `https://dart.dev/get-dart`, or install Flutter
+- **Windows:** install the Dart SDK or Flutter SDK and add its `bin` to PATH
+
+Confirm it resolves:
+
+```bash
+command -v dart
+```
+
+## Configure
+
+Add a `dart` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "dart": {
+    "command": ["dart", "language-server", "--lsp"],
+    "extensionToLanguage": {
+      ".dart": "dart"
+    }
+  }
+}
+```
+
+Claude Code routes `.dart` edits to the Dart language server via the map. No
+extra configuration is normally required.
+
+## Alternatives
+
+None.
+
+## Troubleshooting
+- **PATH:** `dart` must be on PATH; reopen the shell after installing the SDK. Flutter users: ensure `<flutter>/bin/cache/dart-sdk/bin` or the Flutter `bin` is exported.
+- **Flutter vs Dart:** if you only have Flutter installed, the bundled `dart` works — make sure Flutter's `bin` is on PATH rather than relying on a separate Dart install.
+- **SDK out of date:** run `dart --version` / `flutter upgrade` if analysis behaves oddly on newer language features.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.dart
+# or: bun ../../scripts/verify-lsp.ts path/to/file.dart
+```

package/plugins/litclaude/skills/lsp-setup/references/elixir/README.md

@@ -0,0 +1,57 @@
+# Elixir — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `elixir-ls`
+- **Extensions:** `.ex .exs`
+- **Install hint:** `https://github.com/elixir-lsp/elixir-ls`
+
+## Install
+
+ElixirLS needs Erlang/OTP and Elixir installed first. Build the release from
+`https://github.com/elixir-lsp/elixir-ls` and put the `elixir-ls` launcher script on PATH.
+
+- **macOS:** `brew install elixir-ls` (Homebrew provides the launcher), or build the release manually
+- **Linux:** clone elixir-ls, run `mix deps.get && mix compile && mix elixir_ls.release2 -o release`, then add `release/` to PATH
+- **Windows:** build the release and add the `release` dir (use the `.bat` launcher) to PATH
+
+Confirm it resolves:
+
+```bash
+command -v elixir-ls
+```
+
+## Configure
+
+Add an `elixir` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "elixir": {
+    "command": ["elixir-ls"],
+    "extensionToLanguage": {
+      ".ex": "elixir",
+      ".exs": "elixir"
+    }
+  }
+}
+```
+
+Claude Code routes `.ex`/`.exs` edits to `elixir-ls` via the map. No extra
+configuration is normally required.
+
+## Alternatives
+
+- **lexical**: set the `command` to `["lexical"]` — fast, modern alternative LSP.
+- **next-ls**: set the `command` to `["nextls", "--stdio"]` — from the elixir-tools project.
+
+## Troubleshooting
+- **PATH:** `elixir-ls` must be on PATH; reopen the shell after install.
+- **asdf users:** the launcher is a shim — after `asdf install`, run `asdf reshim elixir` so the `elixir-ls` shim resolves, and ensure the Erlang/Elixir versions match the build.
+- **First start is slow:** ElixirLS compiles your deps on first run; initial diagnostics can take a while on large projects.
+- **OTP mismatch:** build elixir-ls with the same Erlang/Elixir versions you use for the project to avoid bytecode errors.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.ex
+# or: bun ../../scripts/verify-lsp.ts path/to/file.ex
+```

package/plugins/litclaude/skills/lsp-setup/references/go/README.md

@@ -0,0 +1,59 @@
+# Go — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `gopls`
+- **Extensions:** `.go`
+- **Install hint:** `go install golang.org/x/tools/gopls@latest`
+
+## Install
+
+- **macOS:** `go install golang.org/x/tools/gopls@latest` (or `brew install gopls`)
+- **Linux:** `go install golang.org/x/tools/gopls@latest`
+- **Windows:** `go install golang.org/x/tools/gopls@latest`
+
+Requires the Go toolchain. `go install` drops the binary in `$GOPATH/bin`
+(default `~/go/bin`) — that directory must be on PATH.
+
+```bash
+export PATH="$PATH:$(go env GOPATH)/bin"
+```
+
+Confirm it resolves:
+
+```bash
+command -v gopls
+```
+
+## Configure
+
+Add a `go` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "go": {
+    "command": ["gopls"],
+    "extensionToLanguage": {
+      ".go": "go"
+    }
+  }
+}
+```
+
+Claude Code routes `.go` edits to `gopls` via the extension map. Analyses such as
+`staticcheck` are configured in `gopls` settings (e.g. a workspace `settings.json`
+consumed by your editor) rather than in `.lsp.json`.
+
+## Alternatives
+
+None — `gopls` is the official and de facto sole Go language server.
+
+## Troubleshooting
+- **PATH:** `gopls` must be on PATH; ensure `$(go env GOPATH)/bin` is exported, then reopen the shell.
+- **No diagnostics / "no required module":** open the directory containing `go.mod` as the workspace root. Outside a module, gopls degrades. Run `go mod tidy` if dependencies are unresolved.
+- **Stale toolchain:** reinstall with `go install golang.org/x/tools/gopls@latest` after upgrading Go.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.go
+# or: bun ../../scripts/verify-lsp.ts path/to/file.go
+```

package/plugins/litclaude/skills/lsp-setup/references/haskell/README.md

@@ -0,0 +1,64 @@
+# Haskell — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `haskell-language-server-wrapper --lsp`
+- **Extensions:** `.hs .lhs`
+- **Install hint:** `ghcup install hls`
+
+The `-wrapper` binary detects your project's GHC version and dispatches to the matching HLS build.
+
+## Install
+
+- **macOS:** `ghcup install hls` (install ghcup via `brew install ghcup` or the official script)
+- **Linux:** `ghcup install hls` (ghcup script from https://www.haskell.org/ghcup/)
+- **Windows:** `ghcup install hls` (ghcup is installed via the Windows installer / PowerShell bootstrap)
+
+HLS needs a working GHC plus Cabal and/or Stack. Install a matching toolchain first:
+
+```bash
+ghcup install ghc
+ghcup install cabal
+```
+
+Confirm it resolves:
+
+```bash
+command -v haskell-language-server-wrapper
+```
+
+## Configure
+
+Add a `haskell` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "haskell": {
+    "command": ["haskell-language-server-wrapper", "--lsp"],
+    "extensionToLanguage": {
+      ".hs": "haskell",
+      ".lhs": "haskell"
+    }
+  }
+}
+```
+
+Claude Code routes `.hs`/`.lhs` edits to the HLS wrapper via the map. Per-project
+plugin/formatter settings normally live in a `hie.yaml` (cradle) and
+`.haskell-language-server` files rather than `.lsp.json`.
+
+## Alternatives
+
+- `ghcide` (the core HLS engine, standalone) — largely superseded by HLS.
+- `hlint` standalone for lint-only checks; `ormolu`/`fourmolu` for formatting.
+
+## Troubleshooting
+- **PATH:** `haskell-language-server-wrapper` on PATH; reopen shell after `ghcup install`.
+- **GHC mismatch:** the installed HLS must support your project's GHC version — run `ghcup install hls` for that GHC, or align GHC to a supported one.
+- **No cradle:** multi-package repos may need a `hie.yaml`; generate one with `gen-hie > hie.yaml`.
+- **Slow first load:** HLS compiles dependencies on first open; let it finish indexing.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/file.hs
+# or: bun ../../scripts/verify-lsp.ts path/to/file.hs
+```

package/plugins/litclaude/skills/lsp-setup/references/java/README.md

@@ -0,0 +1,66 @@
+# Java — LSP setup (Claude Code / LitClaude)
+
+- **Recommended server:** `jdtls`
+- **Extensions:** `.java`
+- **Install hint:** `https://github.com/eclipse-jdtls/eclipse.jdt.ls`
+
+## Install
+
+- **macOS:** `brew install jdtls`
+- **Linux:** Download from [eclipse-jdtls/eclipse.jdt.ls](https://github.com/eclipse-jdtls/eclipse.jdt.ls) releases, extract, and wrap the launcher as `jdtls` on PATH (some distros package it as `jdtls`/`jdt-language-server`).
+- **Windows:** Download the release archive and add the `jdtls` launcher (`bin/jdtls.bat` or the Python wrapper) to PATH.
+
+Requires a **JDK 17+** to run the language server itself (the project may target an older Java version).
+
+Confirm it resolves:
+
+```bash
+command -v jdtls
+```
+
+## Configure
+
+Add a `java` entry to `plugins/litclaude/.lsp.json`:
+
+```json
+{
+  "java": {
+    "command": ["jdtls"],
+    "extensionToLanguage": {
+      ".java": "java"
+    }
+  }
+}
+```
+
+Claude Code routes `.java` edits to `jdtls` via the extension map. jdtls maintains
+a per-project workspace data directory and the first index is slow (it resolves
+the full classpath and builds). If `jdtls` cannot find a runtime, export
+`JAVA_HOME` for a JDK 17+ in the shell that launches Claude Code:
+
+```bash
+export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
+```
+
+Most settings (runtimes, format, import order) come from `settings.java.*`
+defaults and work for Maven/Gradle projects with a standard layout.
+
+## Alternatives
+
+**No mainstream alternative.** `jdtls` (Eclipse JDT Language Server) is the
+de-facto standard and powers the official VS Code Java extension.
+
+## Troubleshooting
+
+- **PATH:** `jdtls` on PATH; reopen shell after install.
+- **No JDK found:** server exits immediately — set `JAVA_HOME` to a JDK 17+.
+- **Slow / no completions at first:** the initial classpath index can take a minute or more on large Maven/Gradle projects; wait for it to finish.
+- **Stale state:** delete the jdtls workspace data dir to force a clean re-index if results go wrong after big dependency changes.
+- **Build tool required:** keep `pom.xml` / `build.gradle` valid; a broken build descriptor breaks symbol resolution.
+
+## Verify
+
+```bash
+node --experimental-strip-types ../../scripts/verify-lsp.ts path/to/File.java
+# or: bun ../../scripts/verify-lsp.ts path/to/File.java
+```