Architecture Note: Neovim's Built-in LSP Client Process Model and Trust Boundaries

When Neovim's built-in LSP client attaches automatically to every opened buffer, a polyglot repository can spawn multiple language server processes with overlapping file access. The editor core remains single-threaded, but each server runs as an independent child process. Without explicit root_dir scoping, a single editing session may launch redundant servers, consume memory unpredictably, and obscure which process owns a given diagnostic. The takeaway: define root_dir narrowly and treat the server command as a privileged input.

Requirements for the Built-in Client

The built-in LSP client must satisfy three architectural requirements: process isolation, protocol correctness, and operational observability. Servers run as child processes communicating over stdio, pipes, or TCP, so a crashing server does not take down the editor. The client must negotiate capabilities during initialize rather than assuming optional features. Observability requires that handshake errors, capability mismatches, and timeouts surface through :messages or server logs rather than failing silently.

Smallest Suitable Design: One Instance, Scoped root_dir

For most projects, the smallest suitable design is a single Neovim instance with per-project root_dir attachment. Rely on community-maintained server definitions rather than building a custom multiplexer. Scope root_dir to the project root—typically identified by a version control marker or language-specific manifest—so a monorepo does not trigger one server per subdirectory.

A minimal configuration might look like this:

-- Place in your Neovim configuration (init.lua)
-- or a project-local .nvim.lua if using exrc
require('lspconfig').gopls.setup{
  root_dir = function(fname)
    return require('lspconfig.util').root_pattern('go.mod', '.git')(fname)
  end,
  cmd = { 'gopls', 'serve' },
}

Here, root_dir is computed per buffer using go.mod or .git as markers. The cmd array defines the executable and arguments. Required permissions: the user running Neovim must be able to execute gopls and read files under root_dir. Expected check: opening a .go file inside that directory should attach exactly one gopls process, visible via :LspInfo. Risk: if root_dir matches too broadly, unrelated directories may share a server instance with unintended file access. Removing the setup block from init.lua reverts to Neovim's default attachment behavior.

Trust and Data Boundaries

The editor trusts the language server binary and its configuration. This is a critical boundary: a server may read arbitrary files under root_dir and, depending on the server, execute code or shell commands. Treat both root_dir and cmd as security-sensitive inputs. In a shared repository, a malicious or compromised project-local configuration could point cmd at an arbitrary executable. Neovim's project-local configuration features amplify this risk because they execute automatically. If you enable project-local configuration, audit the source before opening untrusted workspaces.

Operational Checks

Verify attachment and protocol health with three commands run inside Neovim:

1. :checkhealth — run in normal mode. Review the LSP-related sections to confirm the bundled client and external dependencies are detected. Required permissions: none beyond reading Neovim's runtime.
2. :LspInfo — run in normal mode after opening a project file. The server should report as attached with negotiated capabilities and no error entries. If the server is not listed, the root_dir pattern likely did not match.
3. :messages — run in normal mode to inspect handshake errors, protocol version mismatches, or timeout-induced detach. For persistent logs, redirect server output to a file if the server supports it.

To validate incremental sync, trigger a deliberate syntax error in a source file and confirm diagnostics appear, then correct it and confirm they clear. This exercises the textDocument/didChange notification path without requiring a restart.

Failure Modes

Three failure modes dominate operational incidents:

• Server crashes on large monorepos. A single server process may exhaust memory when indexing a large workspace. Symptom: diagnostics stop updating and :LspInfo shows the client detached. Mitigation: narrow root_dir or switch to a server with incremental indexing.
• stdio buffering deadlocks. If the client writes large requests without draining responses, a chatty server can block. Symptom: the editor hangs or the server becomes unresponsive during bulk edits. Mitigation: prefer servers with proven async stdio handling, or configure the server over TCP for high-throughput scenarios.
• Stale diagnostics after workspace edits. If the client does not send incremental sync updates—or the server ignores them—diagnostics may reference outdated buffer content. Symptom: errors persist after the code is corrected. Mitigation: verify the server advertises textDocumentSync with incremental support during initialization.

When the Design Changes

The single-instance, child-process model breaks under three conditions:

1. Remote or containerized servers. If the language server must run in a container or on a remote host, stdio child processes are no longer available. Switch to TCP transport and ensure the network boundary is authenticated.
2. Workspace scale exceeds single-process memory. When a monorepo is too large for one server process, consider a server that supports multi-process workspaces or shard the root_dir across separate Neovim instances.
3. Untrusted codebases. If you open repositories from untrusted sources, direct child processes grant the server the same privileges as your editor. Use a sandboxed execution environment—such as a container with restricted filesystem access—rather than attaching a server directly.

Limitations and Verification

This note assumes a recent stable Neovim release (0.9 or later) where the built-in LSP client is available without external plugins for basic attachment. Server capabilities vary by language and version; do not assume a server supports all optional features without checking initialize results. Automatic attachment to every opened file can spawn redundant servers, so scope root_dir carefully. To verify the result, open a known project, run :LspInfo, and confirm the server reports attached with expected capabilities. Then introduce and remove a deliberate error to validate the diagnostic lifecycle.