How to Build an LSP Plugin for Claude Code: Real-Time Language Server Feedback in the AI Editing Loop

Language servers give editors structured, real-time feedback about code: diagnostics, hover documentation, autocomplete, and semantic analysis. Claude Code doesn’t have access to this feedback by default — it operates on file contents without the live analysis layer that LSP-enabled editors provide.

An LSP plugin for Claude Code changes that. The plugin routes language server output into Claude’s editing loop, so Claude can read and apply diagnostics, act on hover documentation, and access schema-aware suggestions while it writes code.

The Four-Component Architecture

CircleCI’s guide builds the plugin around four components:

1. Server Launcher — A bash script that downloads the official language server binary, verifies it against a pinned SHA-256 checksum, and caches it locally. The checksum pinning is the security-critical step: it prevents man-in-the-middle substitution of the language server binary and ensures reproducible plugin behavior across environments.

2. Scoping Proxy — A JSON-RPC intermediary that filters documents by file path before passing them to the language server. This is what keeps domain-specific language servers from receiving irrelevant files. A CircleCI config language server should only process .circleci/config.yml files, not all YAML files in the repo — the scoping proxy enforces that boundary.

Without the proxy, a broad-scope language server floods Claude with diagnostics for files outside its domain, degrading signal quality. The proxy is also what makes a single language server useful for monorepos without cross-contaminating domains.

3. Plugin Configuration — A plugin.json file mapping the server to file extensions and startup parameters. This is the integration point between Claude Code’s plugin system and the language server — it tells Claude which files to route to which server and how to launch it.

4. Integration Layer — Optional components for richer language server integration: hover documentation lookup tables generated from schema definitions, custom diagnostic formatting, and other enhancements that surface language server output in forms Claude can act on more directly.

The Benchmark

Controlled testing of the CircleCI config plugin showed that with the LSP plugin and appropriate instructions, Claude added test result storage configuration in 31% of applicable tasks where it would otherwise omit that configuration. The plugin also maintained consistent library version currency.

This is the metric that matters for enterprise adoption: the LSP plugin reduces the category of mistakes where Claude writes syntactically valid but semantically incomplete code — configurations that pass schema validation but miss domain-specific best practices that only the language server knows about.

Generalization Beyond CircleCI

The CircleCI YAML config is the illustrative example, but the architecture generalizes to any language server that speaks LSP. The same pattern applies to:

• Terraform HCL (language server surfaces provider schema violations)
• Kubernetes manifest YAML (language server validates resource API versions and field names)
• Custom DSLs with LSP implementations
• Any domain where schema-aware real-time feedback improves AI code generation quality

The scoping proxy pattern is particularly valuable in polyglot environments: multiple language servers can operate in parallel, each scoped to its specific file types, without creating diagnostic crosstalk.

Source: CircleCI Blog

Content created with AI assistance and reviewed for accuracy.