Skip to main content

LSP Client Matrix

Nudo ships one language server (@nudojs/lsp). Editors differ only in how they launch it and which client-side features they enable. This page is the alignment table: what the server provides, how each client consumes it, and where the gaps are.

The server is designed to run next to tsserver / vtsls, not instead of them.

Known gaps / which limits are client-side (read first)​

Honest positioning. The product gate is nudo check --json plus Agent/MCP tools. The IDE is a best-effort observation surface on the same server — not the gate. Server capabilities are never degraded to match a weaker client; almost every gap below is client UI or client config.

ClientRoleExpectation
VS Code (wmzy.nudo-vscode)Flagship IDE clientFull feature face: hover, CodeLens contract tier + case switch, inlay hints, decorations, agent bridge
ZedBest-effortCore face works (diagnostics / hover / rename). CodeLens needs code_lens: "on"; no active-case decoration API
HelixBest-effortDiagnostics / hover / definition / rename. No CodeLens UI — use CLI nudo contract / nudo check for the same data
NeovimBest-effortCore face works; CodeLens / semantic tokens / decorations depend on plugins
Generic stdio / agent bridgesProtocolworkspace/executeCommand + nudo/… custom requests always available

Gap themes (full table + workarounds below; tracking IDs live in the design source of truth docs/design/lsp-client-gaps.md):

ThemeIDsWho feels it
Active-case decorationLSP-G1Closed on VS Code (function-body + case-line decorations). Zed / Neovim / Helix still open (client has no decoration API, or needs a plugin)
CodeLens not renderedLSP-G2Helix / minimal Neovim — observation face covered by inlay ● contract / hw|gen|imp (same computeContractLenses as CodeLens). CodeLens UI itself remains a client limit
Semantic tokens off by defaultLSP-G3VS Code can paint (semanticTokenScopes). Zed / Neovim / Helix: enable per Setup notes
Secondary-server noise next to tsserverLSP-G4All clients (config: nudo.analysis.include / exclude, or mode: "directives"). VS Code: command Nudo: Apply coexistence settings
Pull diagnostics unusedLSP-G6Older clients — push path is pinned (validateText always publishes); pull is an enhancement
Thin completion / signature help UILSP-G7Server: real paramTypes / return + @nudo: directive completions (@ trigger). Helix UI still varies by build

Rule of thumb: if the protocol serves it but the editor does not draw it, that is a client limitation — fall back to nudo check / nudo contract or the agent tools. Server-side semantics stay identical across editors.

Server capabilities​

Declared on initialize (see @nudojs/lsp API):

CapabilityServer handlerNotes
DiagnosticsvalidateText (push) + diagnosticProvider (pull)Adaptive debounce 300/400/800 ms; cancel-stale generations (A8); pull hits cache only when version + casesHash + depsHash match
HoveronHoverAbs / intension; exported fn name shows ● contract / hw|gen|imp (A7)
Completion (.)onCompletionInferred property/method members
CodeLensonCodeLensObservation selector: ●/○ contract / hw|gen|imp (default active) + persist/update; ●/○ case "…" options follow (nudo.selectCase / nudo.selectContract)
Inlay hintslanguages.inlayHintCase hints + Abs param/return (derived mark on implicit exports)
Definition / References / Renamestandard LSPSidecar binding names included (A5)
Document / workspace symbolsstandard LSP
Signature helponSignatureHelpTriggers (, ,; projects real paramTypes / return via formatShape (G7)
Code actions (quickfix)onCodeActionUnreachable cleanup; contract/param fixes (A6); action-map quickfixes ([fix] / [silence] / [review] / [adjust] / [scaffold])
Semantic tokens (full)languages.semanticTokensLegend includes contract / generated / derived contract modifiers (A7)
Execute commandnudo.*selectCase, contract, contract.draft, contract.emit, agent tools
Custom requestsnudo/…Same handlers as commands (E5); slash-form is the protocol contract
Pull diagnosticsdiagnosticProviderinterFileDependencies: false

File detection (A1/A2): targets are .js / .mjs / .ts. Shipped default is nudo.analysis.mode = "exports" — full gate semantics: Coexistence. CodeLens contract tier uses the broader target path even when diagnostics stay quiet for directive-less files.

Zed / Nvim protocol smoke (B4): pnpm --filter @nudojs/lsp run smoke exercises stdio initialize → textDocument/hover → textDocument/publishDiagnostics — the basic face those editors need. The VS Code package has its own smoke (bundled server + initialize).

Client support matrix​

Legend: Y = works with stock client + this server · C = needs a setting / secondary-server config · N = not available in the client UI (server still serves the protocol) · — = not applicable

CapabilityVS Code (nudo-vscode)Zed (nudo-zed)Neovim (nvim-lspconfig)HelixGeneric stdio LSP
LaunchBundled server.js over IPCZed managed npm (@nudojs/lsp → node …/server.js --stdio)cmd = nudo-lspcommand = nudo-lspSpawn nudo-lsp or node dist/server.js
DiagnosticsYYYYY
Hover (Abs + contract tier)YYYYY
CompletionYYYC (. via auto-pairs)Y
CodeLens contract + caseYC (code_lens: "on")C (plugins: glance/nvim-code-action-menu vary)NC (client-dependent)
Inlay hintsYC (inlay_hints.enabled)C (inlay_hints support)CC
Definition / References / RenameYYYYY
Document symbolsYYYYY
Signature helpYYYCY
Code actions / QuickfixYYYYC
Code actions — extract / inline var / change signatureYYYYC
Semantic tokensYC (semantic_tokens: "combined")C (treesitter/semantic tokens plugin)CC
Active-case decorationY (extension)NNNN
Agent commands (nudo.check, nudo.hover, …)Y (executeCommand / MCP bridge)Y (agent tooling / custom request)Y (custom LSP request)CY
Open-buffer sidecar (A4)YYYYY
Buffer-aware contract agent tool (E5)YYYYY

Setup notes (copy-paste defaults)​

Install @nudojs/lsp so nudo-lsp is on PATH (project-local npm i -D @nudojs/lsp or global). Server freeze inventory: packages/lsp/PUBLIC_API.md / API. Each block below is the recommended default config — copy it whole; every key is documented in the linked client page.

VS Code​

Install wmzy.nudo-vscode. The extension bundles the server and registers nudo.selectCase. See VS Code Extension (includes the maintainer release checklist).

Zed — copy-paste defaults​

  1. Install nudojs/nudo-zed from the extensions registry (or as a dev extension). The extension installs @nudojs/lsp via Zed's managed npm — no package.json pin required.
  2. ~/.config/zed/settings.json (or project .zed/settings.json):
{
"languages": {
"JavaScript": {
"language_servers": ["vtsls", "nudo", "..."]
},
"TypeScript": {
"language_servers": ["vtsls", "nudo", "..."]
}
},
"code_lens": "on",
"inlay_hints": { "enabled": true },
"semantic_tokens": "combined"
}

"..." keeps the remaining registered language servers; code_lens / inlay_hints turn on the CodeLens selector and case hints; semantic_tokens: "combined" layers the server's contract / generated / derived modifiers onto the syntax highlighting. Optional binary override (skip the managed install): "lsp": { "nudo": { "binary": { "path": "nudo-lsp", "arguments": [] } } }. See Zed Extension.

Neovim — copy-paste defaults​

lazy.nvim + nvim-lspconfig (Neovim 0.11+ vim.lsp.config shown; older setups use require("lspconfig").nudo.setup{…} below). The block is a complete default:

-- after installing @nudojs/lsp so `nudo-lsp` is on PATH
vim.lsp.config("nudo", {
cmd = { "nudo-lsp" },
filetypes = { "javascript", "javascriptreact", "typescript", "typescriptreact" },
root_markers = { "package.json", ".git" },
})
vim.lsp.enable("nudo")

-- inlay hints (built-in)
vim.lsp.inlay_hint.enable(true, { bufnr = 0 })

-- optional: CodeLens UI via a plugin (e.g. glance / nvim-code-action-menu)

Basic face check without an editor: pnpm --filter @nudojs/lsp run smoke (hover + push diagnostics over stdio).

Legacy lspconfig form:

require("lspconfig").nudo.setup({
cmd = { "nudo-lsp" }, -- or { "node", "node_modules/@nudojs/lsp/dist/server.js" }
filetypes = { "javascript", "javascriptreact", "typescript", "typescriptreact" },
root_dir = require("lspconfig").util.root_pattern("package.json", ".git"),
})

Agent command example:

vim.lsp.buf.execute_command({
command = "nudo.check",
arguments = { { file = vim.api.nvim_buf_get_name(0) } },
})

Custom request (slash form is the protocol contract):

vim.lsp.buf_request(0, "nudo/check", { file = vim.api.nvim_buf_get_name(0) }, function(err, result) end)

Helix — copy-paste defaults​

~/.config/helix/languages.toml (both javascript / typescript blocks included — copy whole):

[language-server.nudo]
command = "nudo-lsp"
# args = ["--stdio"] # optional; server defaults to stdio when no transport flag is passed

[[language]]
name = "javascript"
language-servers = [ "vtsls", "nudo" ]

[[language]]
name = "typescript"
language-servers = [ "vtsls", "nudo" ]

Helix renders diagnostics / hover / definitions / rename. CodeLens is not in the Helix UI — use CLI nudo contract / nudo check for the same data. Signature help depends on Helix version; if absent, use the CLI/agent tools.

Generic / agent bridges​

Any LSP client can workspace/executeCommand or send nudo/<tool> custom requests. Slash-form (nudo/check) is the protocol contract; dot-form (nudo.check) mirrors command names for MCP-style bridges. Both route to the same handlers (E5). See Agent Integration and the freeze inventory in PUBLIC_API.md.

Known gaps​

Detail behind the read-first summary. Track these when adopting a non-VS Code client. Server-side semantics are shared; gaps are almost always client UI. Every row has a workaround + tracking ID (monorepo truth: docs/design/lsp-client-gaps.md — close a gap there first, then sync this table).

GapAffected clientsWorkaroundTracking
Active-case visual decoration (highlights the selected case function body)Zed, Neovim, Helix (VS Code closed)VS Code extension highlights the whole function body + case line. Elsewhere: CodeLens ●/○ still switches the active case when the client renders CodeLens; hover follows. Without CodeLens UI: CLI nudo check / agent nudo.hover after selectCase via custom requestLSP-G1 — closed on VS Code; client limitation elsewhere (Zed has no decoration API; Neovim needs a custom plugin)
CodeLens not renderedHelix, some minimal Neovim setupsInlay ● contract / … mirrors the CodeLens observation face (same source). Also CLI nudo contract / nudo check; agent nudo.contract / nudo.contract.draft; VS Code/Zed for UI CodeLensLSP-G2 — observation face via inlay; CodeLens UI still client-limited
Semantic tokens off by defaultZed, Neovim, Helix (VS Code can paint)VS Code ships semanticTokenScopes. Elsewhere set client settings from Setup notes (Zed semantic_tokens: "combined"; Neovim treesitter/semantic-tokens plugin; Helix editor.semantic-tokens)LSP-G3 — VS Code ok; config debt on other clients
Secondary-server diagnostics may compete with tsserver noiseAllVS Code: command Nudo: Apply coexistence settings. Or scope package.json#nudo.analysis.include / exclude; or mode: "directives" — full recipe in Coexistence. nudo init prints this pointer (print-only) when the package has tsconfig.json / jsconfig.jsonLSP-G4 — config; VS Code self-serve + coexistence recipe; init prints the pointer
File detection / analysis.mode docsDocsSource of truth: @nudojs/service API + PUBLIC_API.md §7LSP-G5 — closed (docs synced to exports default)
Pull diagnostics unused by some clientsOlder clientsPush path always publishes (validateText / didOpen); clients may ignore diagnosticProvider — pull is optional enhancementLSP-G6 — push face pinned by test
Completion trigger / signature help thin in some UIsHelix (varies by build)Server: real param/return shapes + @nudo: directive completions (trigger @). If the UI is still thin: hover + nudo.check (CLI) / nudo testLSP-G7 — server face improved; Helix UI still client-limited

Same-source guarantee​

These surfaces always share one computation (pinned by tests):

SurfaceShared source
CodeLens ● contractcontractTierOf
Hover first line + contract displaycontractTierOf + getHoverAtPosition
Inlay contractSource / derivedcollectAbsInlays + contractTierOf
Semantic token modifiersbuildSemanticTokens + contractTierOf
Agent nudo.check / nudo.hover / nudo.contract / test/whatIf/traceSame service/core entrypoints + buffer-aware loadModule (E5 AGENT_TOOL_SOURCES); tool errors carry isError: true
CLI nudo check / nudo contractSame service/core entrypoints
executeCommand nudo.* ↔ slash nudo/…Same dispatch table; inventory pinned in packages/lsp/PUBLIC_API.md + public-api-surface.test.ts

See also​