pi-lsp/README.md

@pi/lsp

LSP extension for pi coding agent. Provides LSP tools that the LLM can use to query language servers, plus automatic diagnostics after edit/write operations.

Features

LSP Tools (callable by LLM)

• lsp_hover - Get hover documentation for a symbol
• lsp_definition - Find the definition of a symbol
• lsp_references - Find all references to a symbol
• lsp_completion - Get completion suggestions
• lsp_documentSymbol - Get the symbol outline of a file
• lsp_diagnostics - Get lint/type-check diagnostics

Auto-Check

Automatically runs LSP diagnostics after edit or write tool calls. If issues are found, sends a message with the diagnostics to the LLM.

Enable/disable:

pi --lsp-auto-check=false  # Disable auto-check
pi --lsp-auto-check=true   # Enable (default)

Manual Check Command

Run diagnostics manually on specific files:

/lsp-check main.go utils.go

Install

cd ~/.pi/extensions/lsp
npm install

CLI Usage (for development/testing)

tsx ./cli.ts <file> <lsp_command> <req_data_json>

req_data_json is the raw LSP params for the command, minus textDocument.uri (we inject that from <file>).

Commands

• hover
• definition
• references
• completion
• documentSymbol
• diagnostics (waits briefly for the first publishDiagnostics)

Examples

# Hover at line 224, col 23 (LSP is 0-indexed, so subtract 1)
npm run lsp -- backend/api/server.go hover \
  '{"position":{"line":223,"character":22}}'

# Go to definition
npm run lsp -- backend/api/server.go definition \
  '{"position":{"line":223,"character":22}}'

# Document symbols (no params needed)
npm run lsp -- backend/api/server.go documentSymbol '{}'

# Diagnostics
npm run lsp -- backend/api/server.go diagnostics '{}'

Set LSP_DEBUG=1 to forward server stderr.

Adding A Server

Edit server.ts:

{
  id: "rust-analyzer",
  match: ["rs"],
  command: "rust-analyzer",
  args: [],
  rootMarkers: ["Cargo.toml"],
  languageId: "rust",
}

Adding A Command

1. Add to the LspCommand union in src/types.ts.
2. Add a handler in src/commands.ts.

Future

• Daemon with TTL - ServerConfig.idleTtlMs is reserved for a future daemon that keeps language servers alive per (server.id, rootUri) to avoid cold-start latency. Not implemented; the CLI is short-lived and spawns fresh each invocation.