lspeasy

name	lspeasy
description	Use when working with lspeasy (client, core, server).

lspeasy

Use this skill for ANY work with lspeasy. It routes to the correct package.

When to Use

Use this router when:

• Documentation site for lspeasy
• Documentation site for lspeasy
• Documentation site for lspeasy

Decision Tree

1. Documentation site for lspeasy? → lspeasy-client
2. Documentation site for lspeasy? → lspeasy-core
3. Documentation site for lspeasy? → lspeasy-server

Routing Logic

client → lspeasy-client

Use @lspeasy/client when you need to build the consumer side of the Language Server Protocol — an editor extension, a CLI analysis tool, a test harness, or any process that speaks to a language server process.

• You are implementing a custom client layer and need the same validation behaviour that LSPClient uses. Otherwise this is an internal detail.
• You need to monitor connection liveness — for example, to show a status indicator, trigger reconnection logic, or surface transport errors to users.
• You need to detect silent transport failures — for example, when the server process dies without closing the socket, leaving the client hanging indefinitely on pending requests.

Key APIs: CapabilityGuard, ClientCapabilityGuard, ConnectionHealthTracker

core → lspeasy-core

@lspeasy/core is the shared foundation for the lspeasy SDK. It contains everything needed to build custom LSP integrations, and re-exports the most-used pieces from @lspeasy/client and @lspeasy/server.

• You are building a browser-based LSP client, a WebSocket-backed language server, or any LSP integration that must run over HTTP/HTTPS infrastructure.
• You register multiple handlers (hover, completion, definition) that share the same lifetime — collect them all into one store and dispose the store on shutdown or feature toggle.
• A request handler needs to reject with a machine-readable error code that the client can act on (e.g. respond with MethodNotFound when a capability was not declared, or InvalidParams when schema validation fails).

Key APIs: DedicatedWorkerTransport, SharedWorkerTransport, WebSocketTransport, getCapabilityForRequestMethod, getClientCapabilityForRequestMethod

server → lspeasy-server

Use @lspeasy/server when you need to build the provider side of the Language Server Protocol — a daemon that editors and language-client tooling connect to in order to get diagnostics, completions, hover, go-to-definition, and other language intelligence features.

• The client sets partialResultToken in the request params and you want to stream intermediate results (e.g. symbols found so far) rather than waiting for the complete set.
• A request handler needs to reject with a machine-readable error code that the client can act on (e.g. respond with MethodNotFound when a capability was not declared, or InvalidParams when schema validation fails).

Key APIs: MessageDispatcher, PartialResultSender, ResponseError

Critical Patterns

Top pitfall per package:

• NEVER construct CapabilityGuard before the initialize handshake completes. Server capabilities are only known after the InitializeResult is received; instantiating the guard too early will treat all methods as unsupported. (client)
• Returns null silently when no lsp.json is found anywhere in the search path (including the global ~/.claude/lsp.json fallback). Callers that skip the null check will silently fail to resolve a server command — for the CLI this means lsproxy exits before the proxy daemon is ever spawned. Create an lsp.json at the workspace root or at ~/.claude/lsp.json for a per-user fallback. (core)
• NEVER register the same method in both the request and notification handler registries — the dispatcher uses separate lookup tables and the method will only match one path, silently ignoring the other. (server)

Anti-Rationalization

Thought	Reality
"I'll just use client for everything"	client is for documentation site for lspeasy. The transport already provides its own keep-alive mechanism (e.g. WebSocket ping frames) — adding a heartbeat on top creates redundant round-trips and may interfere with the transport's own timeout logic.
"I'll just use core for everything"	core is for documentation site for lspeasy. You are building a CLI language server — StdioTransport (from @lspeasy/core/node) is the conventional choice and avoids the overhead of a network stack. For same-process workers prefer DedicatedWorkerTransport or SharedWorkerTransport.
"I'll just use server for everything"	server is for documentation site for lspeasy. You want to log a server-side error without sending an error to the client — throw a plain Error and handle it via server.onError() instead.

Example Invocations

User: "I need to documentation site for lspeasy"
→ Load lspeasy-client

User: "I need to documentation site for lspeasy"
→ Load lspeasy-core

User: "I need to documentation site for lspeasy"
→ Load lspeasy-server

NEVER

• NEVER load all package skills simultaneously — pick the one matching your task
• If your task spans multiple packages, load the foundational one first (typically core/shared), then the specific one