Claude Code LSP Integration: Persistent Servers, Push-Based Diagnostics

Most agent coding tools call a language server on demand — ask a question, get a diagnostic, discard.

Claude Code runs a persistent multi-server LSP stack as background infrastructure.

The difference matters: passive diagnostic collection means the agent has up-to-date type errors and reference data without paying a startup cost per query.

File structure

src/
├── services/
│   ├── lsp/
│   │   ├── LSPServerInstance.ts
│   │   ├── LSPDiagnosticRegistry.ts
│   │   ├── LSPManager.ts
│   │   └── lspDiagnosticsTool.ts

Why a persistent stack instead of on-demand

The passive collection model

The most important design choice in the LSP stack is that diagnostic collection is push-based.

Language servers emit textDocument/publishDiagnostics notifications whenever they recompute. The registry listens and updates. The agent does not need to request diagnostics — they are already there when the model asks for context.

This is meaningfully different from a request-response model where the agent asks "what are the current errors in file.ts?" and waits for the server to respond.

With passive collection:

• diagnostic data is available at turn start, not mid-turn
• no round-trip cost per diagnostic request
• the agent can reference "current errors" without triggering a separate tool call

The tradeoff is that the registry may be slightly stale if a server is slow to recompute. Claude Code accepts this tradeoff because staleness on the order of seconds is acceptable for the typical agent coding loop.

The registry bounds are a prompt budget decision

The 10-per-file and 30-total limits are not arbitrary.

They are a prompt budget decision.

If the agent injects diagnostics into a turn's context, those diagnostics consume tokens. Unbounded diagnostics from a project with many type errors could easily fill the available context budget before the actual task is described.

The registry bounds ensure that diagnostic context is always bounded and predictable.

The LRU deduplication ensures that one file with 50 variants of the same null reference error does not consume all 30 slots, leaving no room for diagnostics from other files.

Server routing and multi-language support

LSPTool handles routing transparently.

When the model calls a tool like lsp_go_to_definition with a file path argument, LSPTool:

1. determines the file's language from its extension
2. routes to the appropriate LSPServerInstance for that language
3. sends the JSON-RPC request and returns the result

The model never needs to know which server handles TypeScript versus Python versus Rust. That routing is infrastructure, not capability.

type LSPServerState =
| 'initializing'
| 'ready'
| 'error'
| 'restarting'
| 'stopped'

class LSPServerInstance {
private state: LSPServerState = 'initializing'
private process: ChildProcess | null = null
private capabilities: ServerCapabilities = {}

async start() {
  this.process = spawnLanguageServer(this.serverType)
  const capabilities = await this.initialize()
  this.capabilities = capabilities
  this.state = 'ready'

  this.process.on('exit', () => {
    if (this.state !== 'stopped') {
      this.state = 'restarting'
      this.restart()
    }
  })
}

async sendRequest(method, params) {
  if (this.state !== 'ready') throw new Error('Server not ready: ' + this.state)
  return this.channel.sendRequest(method, params)
}
}

// LSPDiagnosticRegistry: push-based, bounded
class LSPDiagnosticRegistry {
private byFile = new Map()
private totalCount = 0

// Called by server when it pushes textDocument/publishDiagnostics
updateDiagnostics(fileUri: string, diagnostics: Diagnostic[]): void {
  const prev = this.byFile.get(fileUri) ?? []
  this.totalCount -= prev.length

  // Enforce per-file and total bounds
  const bounded = dedupLRU(diagnostics).slice(0, 10)
  const allowedCount = Math.min(bounded.length, 30 - this.totalCount)
  const accepted = bounded.slice(0, allowedCount)

  this.byFile.set(fileUri, accepted)
  this.totalCount += accepted.length
}

getDiagnostics(fileUri?: string): Diagnostic[] {
  if (fileUri) return this.byFile.get(fileUri) ?? []
  return [...this.byFile.values()].flat()
}
}