/wiki / lsp

Lsp — Map of Content

2026-09-02T00:00:00.000Z

Map of Content for Lsp — 7 concepts. Start here to navigate lsp.

Core Concepts

true — concept
true — concept
true — concept
true — concept
true — concept
true — concept
true — concept

Mechanisms & How Things Work

Auto-generated — edit to curate. Pages that explain processes/flows.

Comparisons & Tradeoffs

(No synthesis yet — create via ingest or query —save)

language-server-protocol

2026-04-12T00:00:00.000Z

The Problem

Code editors need to provide intelligent features like go-to-definition, refactoring, and completion. Before LSP, each language required custom integration with every editor—a massive N×M problem. LSP standardizes communication between tools and language analyzers.

Core Idea

The Language Server Protocol (LSP) is a protocol that defines communication between a code editor (client) and a language analysis tool (server). LSP standardizes features like autocomplete, go-to-definition, find references, hover information, rename, and formatting across all languages.

How It Works

Client-Server Architecture: The editor acts as an LSP client; the language analyzer runs as a separate process (language server)
JSON-RPC Communication: Messages are sent over stdin/stdout using JSON-RPC 2.0
Standardized Methods: Features are exposed via methods like textDocument/definition, textDocument/completion, textDocument/rename
Initialization: Client and server exchange capabilities during initialization
Document Synchronization: Server receives notifications when files change via textDocument/didOpen, textDocument/didChange, etc.

Key Properties

Language-agnostic protocol (works with any programming language)
Server provides semantic, project-level analysis (unlike ctags)
Bidirectional: client sends requests, server sends notifications and responses
Capabilities negotiation: servers declare supported features
Standardized request/response format

Connections

Built from: JSON-RPC 2.0 — underlying wire protocol
Builds into: Neovim’s vim.lsp — specific client implementation
Related: Treesitter — alternative code understanding (syntax parsing vs LSP semantic analysis)
Related: Ctags — traditional navigation approach

Edge Cases & Gotchas

Servers are third-party; each language requires separate installation
Not all servers implement all features—check capabilities
Large projects may have performance issues with file watching
Dynamic registration allows servers to add capabilities after initialization

lsp-client

2026-04-12T00:00:00.000Z

The Problem

Once an LSP server is started, the editor needs to manage its state—track attached buffers, send requests, handle responses, and monitor capabilities. This requires an abstraction representing the active LSP connection.

Core Idea

An LSP Client is a Neovim object representing an active connection to a language server. It holds the server’s capabilities, attached buffers, pending requests, and methods for interaction.

How It Works

Creation: vim.lsp.start() or vim.lsp.enable() creates a client from a config
Retrieval: vim.lsp.get_client_by_id(id), vim.lsp.get_clients({filter})
Capabilities: client.server_capabilities exposes what the server supports
Request tracking: client.pending_requests tracks in-flight requests
Buffer association: client.attached_buffers maps to buffers using LSP
Methods: client.request(), client.notify(), client.cancel_request()

Key Properties

Unique id for referencing the client
name from config or default
server_capabilities populated after initialization
root_dir derived from config or root_markers
Can attach to multiple buffers simultaneously

Connections

Built from: LSP Configuration — config creates client
Builds into: vim.lsp — clients are managed by vim.lsp
Related: LSP Events — events fired based on client activity

Edge Cases & Gotchas

Client may not be fully initialized when first returned
Dynamic registration can add capabilities after LspAttach
Stopped clients return nil from get_client_by_id
Request cancellation triggers LspRequest event with type=cancel

lsp-configuration

2026-04-12T00:00:00.000Z

The Problem

Different language servers need different startup commands, file type associations, and workspace detection rules. Users and plugins need a unified way to define and share LSP configurations without code duplication.

Core Idea

LSP Configuration in Neovim uses vim.lsp.config() to define server settings, with a merge chain that allows global defaults, plugin configs, and user overrides to coexist.

How It Works

Definition: vim.lsp.config('server-name', {cmd = {...}, filetypes = {...}, root_markers = {...}})
Enable: vim.lsp.enable('server-name') activates auto-attachment for matching buffers
Merge Priority (lowest to highest):
- Global config (vim.lsp.config('*', {...}))
- lsp/<name>.lua files in runtimepath
- after/lsp/<name>.lua files
- Direct config calls in init.lua
Config sources: Can also use lsp/<name>.lua files in runtimepath

Key Properties

Wildcard * config applies to all servers
root_markers can be nested for equal-priority markers: {{'a', 'b'}, 'c'}
Config merging uses vim.tbl_deep_extend with “force” behavior
Config files in runtimepath may be eagerly evaluated (performance note)
“after/” directory follows standard Vim after-directory semantics

Connections

Built from: vim.lsp — the framework providing config()
Builds into: LSP Client — configs become client instances via enable/start
Related: Root Markers — part of config that determines workspace
Related: LSP Events — lifecycle events triggered for configured clients

Edge Cases & Gotchas

Using vim.lsp.config['name'] has side-effect of resolving config
Prefer vim.lsp.is_enabled() to check status without resolving
Place configs in after/lsp/ to override plugin defaults

lsp-events

2026-04-12T00:00:00.000Z

The Problem

Plugins and users need to react to LSP lifecycle events—attach to buffers, respond to progress, handle document changes. Neovim needs a way to signal when these events occur so users can customize behavior.

Core Idea

LSP Events are Neovim autocmd events triggered during LSP client lifecycle: LspAttach (client initializes), LspDetach (client disconnects), LspProgress (server sends progress), LspRequest (request status changes), LspNotify (notification sent), LspTokenUpdate (semantic token changed).

How It Works

LspAttach: Fired after client initializes and attaches to buffer; provides client_id in event data
LspDetach: Fired just before client detaches; clean up custom handlers here
LspProgress: Triggered on progress notifications; use for statusline updates
LspRequest: Fires on request send, completion, or cancellation; track pending work
LspNotify: Fires after each successful notification to server
LspTokenUpdate: Fires when semantic tokens change; for custom token highlighting

Key Properties

Use vim.api.nvim_create_autocmd() with event name
Event data passed to callback contains client_id, method, params, etc.
LspProgress pattern can be filtered by work done kind (begin/report/end)
Dynamic registration may add capabilities after LspAttach

Connections

Built from: LSP Client — events relate to client lifecycle
Builds into: vim.lsp — vim.lsp triggers these events
Related: Semantic Tokens — LspTokenUpdate for token changes

Edge Cases & Gotchas

Dynamic registration can happen after LspAttach; handle registerCapability event
LspDetach is the place to remove buffer-local autocmds (like format on save)
LspRequest with type=complete deletes pending request after handler runs
LspTokenUpdate is experimental beyond calling highlight_token()

lsp-root-markers

2026-04-12T00:00:00.000Z

The Problem

LSP servers need to know the project root to provide accurate analysis—finding dependencies, resolving imports, understanding project structure. Without knowing the root, the server might behave incorrectly or provide incomplete results.

Core Idea

Root Markers are files or directories (like .git, package.json, pyproject.toml) that Neovim uses to identify the project workspace root. When a buffer matches a config’s filetypes, Neovim searches upward for root markers to determine where the LSP server operates.

How It Works

Config specifies root_markers: {'.git', 'package.json', 'pyproject.toml'}
When enabling LSP for a buffer, Neovim searches upward from the buffer’s directory
First marker found determines the root; search stops at that directory
Multiple markers in nested array have equal priority: {{'a', 'b'}, 'c'} means find either a or b first, else c
If root_dir is explicitly defined, root_markers are ignored

Key Properties

Marker can be a file or directory name
Order in the array determines search priority
Nested arrays indicate equal-priority markers
Can be overridden by explicit root_dir function
Used by vim.lsp.enable() for auto-activation decisions

Connections

Built from: LSP Configuration — part of config
Builds into: LSP Client — root_dir becomes client property
Related: vim.lsp — used by enable() for workspace detection

Edge Cases & Gotchas

Without matching root markers, LSP won’t auto-activate
Search traverses upward until root filesystem or found
Polyglot projects may need careful marker ordering
Some languages have specific markers (e.g., .clangd for clangd)

lsp-semantic-tokens

2026-04-12T00:00:00.000Z

The Problem

Syntax highlighting shows code structure (keywords, strings, comments) but not semantic meaning (is this a function? a class? deprecated?). Treesitter provides syntax-level highlighting, but LSP servers have additional semantic knowledge about the code that can enhance the editing experience.

Core Idea

Semantic Tokens are LSP protocol extensions that let servers provide additional highlighting based on semantic meaning—identifying functions, variables, classes, parameters, and their modifiers (readonly, async, deprecated, etc.). This works alongside Treesitter, not replacing it.

How It Works

Server advertises textDocument/semanticTokens capability during initialization
Server sends tokens as ranges with type (function, variable, class) and modifiers (readonly, async)
Neovim applies highlight groups: @lsp.type.<type>.<filetype>, @lsp.mod.<mod>.<filetype>
Can combine type+modifiers: @lsp.typemod.<type>.<mod>.<filetype>
LspTokenUpdate event fires when tokens change (for custom highlighting)

Key Properties

Adds to Treesitter highlighting, doesn’t replace it
Standard types: class, function, method, variable, parameter, etc.
Standard modifiers: readonly, async, deprecated, static, abstract
Highlight groups can be customized via hi or nvim_set_hl
Priority: @lsp.type._ = semantic_tokens, @lsp.mod._ +1, @lsp.typemod.* +2

Connections

Related: Treesitter — provides syntax-level highlighting
Builds into: LSP Events — LspTokenUpdate for token changes
Related: vim.lsp — handles semantic token integration

Edge Cases & Gotchas

Semantic highlights are additive to Treesitter—not a replacement
Servers may use non-standard types/modifiers beyond the specification
Disable by clearing highlight groups in ColorScheme autocmd
LspTokenUpdate only supports highlight_token() call; other uses experimental

vim-lsp

2026-04-12T00:00:00.000Z

The Problem

Neovim needs a built-in way to connect to LSP servers without requiring external plugins. The built-in LSP client should handle the complexity of starting servers, managing clients, and exposing a Lua API for interacting with language servers.

Core Idea

vim.lsp is Neovim’s built-in Lua framework for creating LSP clients and building LSP-powered tools. It provides functions to start/configure language servers, handle LSP methods, and implement editor features using semantic analysis.

How It Works

Configuration: Use vim.lsp.config() to define server configurations (cmd, filetypes, root_markers)
Activation: Use vim.lsp.enable() to auto-start LSP for matching buffers
Client Management: vim.lsp.start() creates a client; vim.lsp.get_clients() retrieves active clients
Buffer Operations: vim.lsp.buf.* functions operate on the current buffer (definition, references, hover)
Handler System: Custom handlers can intercept/override LSP responses at multiple levels

Key Properties

Built-in (no plugin required for basic LSP)
Lua-native API (vim.lsp.buf, vim.lsp.client)
Config merging from multiple sources (global, runtimepath, after/)
Built-in keymaps and buffer-local options for common features
Event-driven: LspAttach, LspDetach, LspProgress, etc.

Connections

Built from: LSP — the protocol it implements
Builds into: LSP Configuration, LSP Client, LSP Events, Semantic Tokens
Related: Root Markers — workspace detection
Contrasts with: Treesitter — syntax parsing vs semantic analysis

Edge Cases & Gotchas

Config files in runtimepath are eagerly evaluated
Global keymaps are created unconditionally on startup
Default buffer-local settings (omnifunc, tagfunc, formatexpr) can conflict with other plugins
Large workspaces: file watching can cause performance issues on Linux

/wiki / lsp

Lsp — Map of Content

Core Concepts

Mechanisms & How Things Work

Comparisons & Tradeoffs

Suggested Reading Order

language-server-protocol

The Problem

Core Idea

How It Works

Key Properties

Connections

Edge Cases & Gotchas

lsp-client

The Problem

Core Idea

How It Works

Key Properties

Connections

Edge Cases & Gotchas

lsp-configuration

The Problem

Core Idea

How It Works

Key Properties

Connections

Edge Cases & Gotchas

lsp-events

The Problem

Core Idea

How It Works

Key Properties

Connections

Edge Cases & Gotchas

lsp-root-markers

The Problem

Core Idea

How It Works

Key Properties

Connections

Edge Cases & Gotchas

lsp-semantic-tokens

The Problem

Core Idea

How It Works

Key Properties

Connections

Edge Cases & Gotchas

vim-lsp

The Problem

Core Idea

How It Works

Key Properties

Connections

Edge Cases & Gotchas