LSP

Overview

nikcli uses Language Server Protocol servers as an optional code-intelligence layer for tools, diagnostics, symbols, definitions, references, hover information, implementations, and call hierarchy. The service lives under packages/nikcli/src/lsp and is loaded through an Effect service, so every project instance gets its own LSP state, root detection, client list, and shutdown finalizer.

Runtime lifecycle

The service state is created from the current instance context and current config. If lsp is set to false, the service keeps an empty server map and all operations become unavailable. Otherwise nikcli loads every built-in server from LSPServer, filters experimental servers, applies config overrides, and records a finalizer that shuts down every connected client when the instance is disposed.

1. Resolve config from global, project, and remote sources through Config.defaultLayer.
2. Build the server map from packages/nikcli/src/lsp/server.ts.
3. Apply experimental filtering: ty replaces pyright only when the Python flag is set.
4. Merge overrides: disabled entries are removed; command overrides replace spawn behavior.
5. Spawn on demand when touchFile, hasClients, or an LSP operation needs a matching extension.
6. Initialize JSON-RPC with root URI, workspace folders, diagnostics, watched-file support, and configuration support.
7. Cache clients by root plus server id, mark broken pairs, and reuse in-flight spawns.
8. Dispose cleanly by ending the JSON-RPC connection and killing the child process.

Supported servers

The built-in catalog is declared in packages/nikcli/src/lsp/server.ts. Each entry has an id, extension list, root strategy, and spawn function.

Root detection

Root selection is server-specific. Most entries use NearestRoot, which walks upward from the file directory toward the current nikcli instance directory and returns the directory containing a matching marker file. If no marker exists, some servers fall back to the current instance directory; others return no root and do not start.

Agent tool

The lsp tool in packages/nikcli/src/tool/lsp.ts exposes editor-like navigation to agents. It accepts a file path, one-based line and character values, asks for lsp permission, opens the file through the LSP client, waits briefly for diagnostics, and then runs the selected operation.

Debug commands

The debug command group touches files and prints raw LSP JSON responses. Use it to check whether root detection, server startup, and diagnostics are working before relying on agent calls.

nikcli debug lsp diagnostics packages/nikcli/src/lsp/index.ts
nikcli debug lsp symbols Session
nikcli debug lsp document-symbols file:///absolute/path/to/file.ts

Diagnostics waits for a publish event after opening the file, sleeps briefly, and then prints the collected diagnostics map. Symbol commands call the service directly and print JSON.

Configuration

The lsp config field accepts false to disable all language servers, or a server-id map to disable, override, or add servers. Custom server ids must declare extensions, because nikcli otherwise cannot know which files should start them.

Dot-path config sketch

lsp.typescript.disabled = true
lsp.my-language.command = my-language-server --stdio
lsp.my-language.extensions = .my, .mine
lsp.my-language.env.MY_LANGUAGE_MODE = strict
lsp.my-language.initialization.workspaceMode = full

Downloads and binaries

Some servers require a system binary in PATH. Others install language-server packages or release binaries into Global.Path.bin, which resolves to the bin directory under nikcli's data root. Auto-downloads are skipped when NIKCLI_DISABLE_LSP_DOWNLOAD is set.

Diagnostics and symbols

When a file is opened, nikcli sends workspace/didChangeWatchedFiles and textDocument/didOpen. If the same file is touched again, it sends a watched-file change plus textDocument/didChange with an incremented version. Published diagnostics are normalized to filesystem paths and stored per client.

• Diagnostics debounce waits for the matching path and server id, then resolves after a short quiet period.
• TypeScript first diagnostic quirk suppresses the first TypeScript publish event when the file had no diagnostic entry yet.
• Workspace symbols filter to classes, functions, methods, interfaces, variables, constants, structs, and enums.
• Document symbols accept a file URI and return raw document or location symbols after filtering empty values.

Failure modes

Source anchors