crux lsp

crux lsp brings Project Index lint findings into editors that support the Language Server Protocol. It publishes diagnostics for TypeScript and JavaScript files, keeps their ranges aligned with unsaved edits, explains each finding on hover, and offers the actions declared by its rule. It also projects indexed definitions and relations into editor navigation, symbols, definition hover, inlay hints, and code lenses. In supported first-party dependency slots, it adds Project Index-aware semantic completion.

Command

crux lsp
crux lsp --port 4500
crux lsp --root packages/app

The command speaks JSON-RPC over stdio. Editors should start it directly as crux lsp; do not wrap it in a shell or add a transport flag. Human-readable logs go to stderr so stdout remains an LSP-only stream.

Attach and own modes

The language server chooses the read model independently for each Crux workspace folder:

• When a crux dev server on the configured port reports the same project root, the language server attaches to its live Project Index.
• When no matching server is available, it runs the same Project Index watcher in its own process.
• If an attached server disconnects, existing diagnostics stay visible while the language server reconnects. It falls back to its own watcher after the reconnect grace period.
• While indexing on its own, it periodically checks for a matching dev server and hands over without clearing diagnostics first.

A dev server for another project on the same port is never attached. A version mismatch produces a warning but keeps the server attached because the dev server's read model is authoritative.

Indexing remains save-based: unsaved content never changes Project Index results. The language server consumes incremental document changes to keep published ranges aligned with the edited buffer. While a document is dirty, new disk-derived positions are held until save so an authoritative reindex cannot move a squiggle back to stale buffer coordinates. Closing the document ends buffer tracking; the next authoritative update restores disk positions. Authoritative clears still apply immediately.

Semantic completion is the one feature that parses current unsaved text. Its bounded overlay is request-only and never becomes Project Index or cache state. See Semantic completion for supported slots, import behavior, privacy, limits, and exclusions.

Visual Studio Code and compatible editors

The Crux extension starts one language client for the window, discovers the Crux binary, renders optional inline finding text, forwards server settings, and registers Crux: Open Devtools and Crux: Restart Language Server. It activates in workspaces containing crux.config.ts, crux.config.js, or crux.config.mjs.

The extension requires workspace trust. In Restricted Mode, the editor host does not activate it: no binary is discovered or started, and no workspace configuration is loaded. Granting trust activates the extension normally. The language server independently validates command actions and accepts only its fixed command allowlist as defense in depth.

Install the extension and CLI

Crux currently distributes its editor extension and native archives through GitHub Releases. The extension and CLI are versioned in lockstep. Choose the latest stable release for normal use; entries marked Pre-release are nightly builds from the exact source commit named in their release notes.

The recommended installation is the npm CLI plus the VSIX from the same release:

npm install -g @use-crux/local
code --install-extension crux-vscode-<version>.vsix

In VS Code, Cursor, or another compatible editor, you can instead run Extensions: Install from VSIX... and select the downloaded file. A VSIX installed from GitHub does not update automatically; download and install the new VSIX when changing Crux versions.

For a project-local CLI, install the package in the workspace:

npm install --save-dev @use-crux/local

Without an explicit path, discovery checks repository build outputs, the project-local node_modules/.bin/crux shim (crux.cmd on Windows), native workspace executables including crux.exe, a workspace-root binary, and finally PATH. The selected candidate must be executable and return a non-empty version from --version. An invalid explicit crux.binaryPath is an error and never silently falls through.

Direct download

As an npm-free alternative, download the VSIX, SHA256SUMS, and the archive for your system from the same release:

Verify the downloaded archive and VSIX against their exact rows before extracting them:

grep '  crux-<version>-linux-x64.tar.gz$' SHA256SUMS | sha256sum -c -
grep '  crux-vscode-<version>.vsix$' SHA256SUMS | sha256sum -c -

grep '  crux-<version>-darwin-arm64.tar.gz$' SHA256SUMS | shasum -a 256 -c -
grep '  crux-vscode-<version>.vsix$' SHA256SUMS | shasum -a 256 -c -

$file = "crux-<version>-win32-x64.zip"
$expected = ((Select-String -Path SHA256SUMS -Pattern "  $file$").Line -split "  ")[0]
(Get-FileHash -Algorithm SHA256 $file).Hash.ToLower() -eq $expected

Checksums protect download integrity; the GitHub repository and release are the publisher-identity boundary. Extract the archive and keep crux (or crux.exe) beside crux-static-index-worker (or its .exe). Set crux.binaryPath to the extracted CLI. Direct-download binaries do not update automatically.

For a repository build instead, run pnpm install, build the extension, and package it with pnpm --filter crux-vscode package.

Other LSP editors

Use the editor's custom language-server configuration with this equivalent shape:

command: crux
args: [lsp]
transport: stdio
languages: [typescript, typescriptreact, javascript, javascriptreact]
root_markers: [crux.config.ts, crux.config.js, crux.config.mjs]

Pass --port <port> in args when crux dev does not use port 4400. Pass --root <dir> only for clients that do not send workspaceFolders or rootUri; editor-provided roots take precedence.

Settings

VS Code settings use the names below. Other clients can send the same nested crux object in initializationOptions or workspace/didChangeConfiguration.

Changing the lint profile or suppression setting re-filters the current read model without reindexing. Inlay-hint and code-lens changes apply live. Changing the port or binary path makes the VS Code extension restart the language client. Decoration settings are client-side presentation settings and are never sent to the language server.

Navigation and definition context

Crux navigation reads the same indexed definitions, source references, and relations as diagnostics:

• Go to Definition follows indexed source references and relation sites to their owning prompt, context, tool, agent, or other Crux definition.
• Find All References returns indexed relation and source-reference sites, with the declaration included when the client requests it.
• Document Symbols adds the file's Crux definitions to Outline.
• Workspace Symbols searches definition names and ids across Crux workspace folders. Results identify their folder in multi-root workspaces.

Navigation ranges use the displayed document view. They follow unsaved edits without reindexing, while newer disk-derived positions remain held until save just like diagnostic ranges.

Hovering an indexed definition shows its name, kind, description when present, current finding count, and incoming/outgoing relation counts. When a diagnostic also matches the position, the definition section follows the finding details.

Definitions with current findings receive two independent, live-configurable signals:

• An inlay hint such as ⚑ 2 findings at the end of the definition's first source line.
• A code lens such as Crux: 2 findings above the definition. While attached to crux dev, the VS Code extension makes it clickable and opens that exact definition in the Devtools Catalog. In own mode, or in clients that do not declare the client-side command, the count remains visible but informational.

Definitions without findings receive neither signal.

Diagnostics and actions

Diagnostics appear under the crux source and retain the rule's severity, except experimental findings are shown as hints. Rule codes link to the rule reference when the editor supports diagnostic code links.

Hovering a Crux diagnostic shows its title, rule id, severity, maturity, confidence, instance-specific message, rationale, impact, suppression details when available, and rule-documentation link. When several findings overlap, the hover includes up to three and reports the remaining count.

For rules with next-line suppression support, Quick Fix inserts the rule's exact // crux-lint-disable-next-line ... directive above the affected line while preserving indentation. Save the file to reindex it.

Some manual fixes also declare crux runtime generate as a companion command. In a trusted VS Code workspace, their quick fix is titled Run crux runtime generate — fix title. The server resolves the current finding and fix from its read model, accepts only the exact built-in command, and starts its own binary directly without a shell. It reports command success or failure in the editor.

The command regenerates runtime artifacts; it does not rewrite the authored source that caused the finding. Make the documented source correction, run the command when appropriate, and save to clear the finding through normal reindexing. Command actions are unavailable in untrusted workspaces. Fix-all actions are not supported.

Inline decorations

The VS Code extension can render one compact annotation after each affected line. It selects the most severe Crux diagnostic on that line, appends +N when more findings share it, and uses the editor theme's diagnostic color at a subdued opacity. Decorations read the editor's published diagnostics directly; they add no language-server traffic and follow the same live range shifts.

crux.decorations.mode controls coexistence with general inline-diagnostics extensions:

• auto enables Crux decorations unless Error Lens (usernamehw.errorlens) or Reason Error Lens (PolyMeilex.reason-error-lens) is installed and active.
• on always enables them.
• off clears them immediately.

Only visible editors are decorated. Suppressing a finding and saving removes its annotation after the normal reindex unless suppressed findings are included. Changing crux.decorations.opacity rebuilds the editor decoration types and refreshes visible editors without restarting the language server.

Related

• @use-crux/local
• Project Index
• Lint