LSP Server

Bifrost can run as a Language Server Protocol server over stdio. Start it with an explicit workspace root:

bifrost --root /path/to/project --lsp

The server does not open a network port. It speaks LSP over stdin and stdout, builds the workspace index in the background, and lets the first request wait for indexing when necessary.

Workspace Root

--root is the fallback workspace root. During LSP initialization, clients may send workspaceFolders, rootUri, or rootPath; Bifrost uses those client-provided roots when available. Use --root to make the server process deterministic and to provide a fallback when the client does not send a usable workspace root.

Clients can also pass Bifrost-specific initializationOptions:

{
  "roots": ["src", "tests"],
  "exclude": ["target", "vendor/generated"],
  "unrecognizedSymbolDiagnostics": false
}

roots limits indexing to selected directories under the fallback root. exclude removes generated output, dependency caches, or other directories from workspace symbols and document-level lookups.

Runtime Configuration

Bifrost supports the LSP 3.18 workspace/didChangeConfiguration notification. When the client advertises workspace.configuration, Bifrost requests the complete bifrost section with workspace/configuration. Clients without configuration-pull support can push the complete settings object directly or nest it under bifrost:

{
  "settings": {
    "bifrost": {
      "roots": ["src", "tests"],
      "exclude": ["target"],
      "formatterCommands": [],
      "unrecognizedSymbolDiagnostics": false
    }
  }
}

Each accepted runtime value is a full snapshot. It replaces the startup initializationOptions and the previous runtime value; omitted or empty roots, exclude, formatterCommands, and unrecognizedSymbolDiagnostics fields therefore reset those settings to their defaults. Unknown fields are ignored, while an invalid recognized field rejects the complete snapshot and leaves the last working configuration active.

Changing only formatterCommands affects later formatting requests without rebuilding the analyzer. Changing roots or exclude rebuilds the workspace, preserves open editor buffers, cancels active formatter processes before swapping state, and clears published diagnostics for files that leave the workspace. Clearing roots restores the latest workspace folders reported by the editor.

unrecognizedSymbolDiagnostics is an experimental opt-in lint. It is false by default because Bifrost’s symbol resolver is not yet accurate enough to make those editor errors trustworthy. Set it to true to publish unrecognized symbol and member diagnostics; syntax diagnostics are always enabled.

Protocol Surface

Bifrost advertises LSP capabilities only after the matching handler exists. Unsupported requests return JSON-RPC MethodNotFound; unsupported notifications are ignored.

Current support includes incremental and whole-document text synchronization, save notifications, diagnostics, definition/type-definition/implementation, hover, signature help, completion, references, rename, document highlights, document symbols, full-document semantic tokens, formatting, folding ranges, workspace symbols, type and call hierarchy, workspace folder and runtime configuration changes, watched-file notifications, startup progress, formatting cancellation, and cooperative cancellation plus client-owned work-done progress for references requests.

Semantic tokens color analyzer-known declarations and structured references from the current overlay-aware document snapshot. Bifrost advertises a stable high-level legend to compatible clients and leaves ordinary syntax coloring to the editor; semantic-token range and delta requests are not currently advertised. To keep the serial LSP request loop responsive, documents larger than 1 MB or with more than 10,000 structured identifier candidates receive an empty semantic-token result. Go workspaces above 64 files or 2 MB of current source receive declaration tokens without the more expensive workspace-wide reference resolution.

References progress is emitted only when the request supplies a workDoneToken; partial reference results are not streamed. Broader cancellation/progress support for workspace symbols, diagnostics, semantic tokens, and hierarchy remains an intentional follow-up area. Code actions, server-side execute commands, and pre-save hooks are not advertised until Bifrost has concrete safe edits or commands to expose.

CLI Tooling

For terminal checks and scripts, use one-shot CLI tool mode instead of starting an LSP session.