@gitawego/pi-lsp

Config-driven Language Server Protocol integration for the pi coding agent. Official LSP servers by default, persistent per-project sessions, progressive diagnostics after edits, and rich query tools.

Cross-platform (64-bit only): Linux, macOS, Windows, and android-arm64 (Termux).

Install

pi install git:github.com/gitawego/pi-lsp

Remove the older @narumitw/pi-lsp if installed:

pi remove npm:@narumitw/pi-lsp

Reload with /reload (or restart pi).

Tools

Tool	Purpose
lsp_diagnostics	Diagnostics for files/directories via the file's LSP server
lsp_status	Live LSP server sessions (id, root, status)
lsp_fix	Apply a source code action (default source.fixAll; preview unless write: true)
lsp_hover	Hover documentation at a position
lsp_definition	Definition locations for the symbol at a position
lsp_references	All references (including the declaration)
lsp_implementation	Implementations of the symbol at a position
lsp_symbols	Symbols declared in a file
lsp_workspace_symbol	Workspace-wide symbol search by query (up to 10 results)
lsp_call_hierarchy	Call hierarchy: prepare / incoming / outgoing
lsp_rename	Workspace rename edits (preview only — never writes)

Also: /lsp command (session status) and a lsp statusline entry while servers start.

Progressive diagnostics

After each agent turn, files the agent edited (edit, write, lsp_fix, bash redirects) are re-synced with the live LSP sessions and a throttled, compact diagnostics summary is surfaced. The surface is config-driven (progressive.inject):

• status (default) — statusline summary
• widget — reserved; TUI widget
• conversation — injected into the conversation via a custom message
• none — disabled

Default catalog (official servers)

Server	Languages	Install strategy
typescript	.ts .tsx .js .jsx .mjs .cjs .mts .cts	typescript-language-server (npm, auto)
kotlin	.kt .kts	kotlin-lsp (GitHub release; needs java)
gopls	.go	gopls (go-install; needs go)
rust-analyzer	.rs	rust-analyzer (PATH only)
clangd	.c .h .cpp .cc .cxx .hpp .hh .hxx	clangd (PATH; ships with Termux)
pyright	.py	pyright-langserver (npm)
ruby-lsp	.rb .rake .gemspec .ru	ruby-lsp (PATH)
elixir-ls	.ex .exs	elixir-ls (PATH)
zls	.zig .zon	zls (PATH)

The TypeScript server is the official typescript-language-server — never a linter standing in for a type-checker.

Platform matrix (64-bit only: arm64 / x64)

Strategy	Works on
npm (typescript, pyright)	everywhere, including android-arm64 (pure JS)
github-release (kotlin-lsp)	Linux/macOS/Windows with java; refused on android (bionic)
go-install (gopls)	anywhere with go on PATH
PATH-only (rust-analyzer, clangd, ruby-lsp, elixir-ls, zls)	wherever the binary is installed; clangd ships with Termux

Kotlin on android-arm64 (verified): the official JetBrains kotlin-server does boot on Termux via glibc-runner -n <bin> --stdio (ELF patched to the $PREFIX/glibc loader), and the plugin can drive it via a config override. However, its IntelliJ-based analysis did not produce diagnostics within 3–10 minutes on this hardware, so kotlin defaults to PATH-only on android. If you have a JVM-based Kotlin LSP on PATH, it works via config: "kotlin": { "command": ["java", "-jar", "/path/to/server.jar"] }.

32-bit architectures (ia32, arm, …) are unsupported: managed installs are refused and the platform is reported as unsupported — never a crash.

Configuration (config-driven)

Configuration is resolved from pi-lsp.json in this order (each may override the previous):

1. Default official-server catalog
2. User: ~/.pi/agent/pi-lsp.json
3. Project: <workspace>/.pi/pi-lsp.json (only when pi trusts the project)

{
  "timeout": 30000,
  "binDir": "~/.cache/pi-lsp/bin",   // managed installs
  "progressive": {
    "enabled": true,
    "inject": "status",              // status | widget | conversation | none
    "maxDiagnostics": 20,
    "quietMs": 2000
  },
  "servers": {
    "typescript": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"]
    },
    "kotlin": { "disabled": true },  // drop a default server
    "my-lang": {                     // add a custom server
      "command": ["my-lang-lsp", "--stdio"],
      "extensions": [".mylang"]
    }
  }
}

Per-server options: command, extensions, languageId, rootMarkers, env, initialization, autoDownload, disabled. Invalid or unreadable files fall back to defaults for that source.

How it works

OpenCode-inspired architecture: one persistent LSP client per (project root, server), discovered lazily with marker-file root detection (package-lock.json, go.mod, settings.gradle.kts, …), kept alive for the session, and shut down at session_shutdown. Documents are tracked with versions; touchFile sends didChangeWatchedFiles + didOpen/didChange; diagnostics merge push (publishDiagnostics) and pull (textDocument/diagnostic) results with dedupe. Servers that fail to start are marked broken (no retry storms).

The manager API mirrors OpenCode's LSP service interface (packages/opencode/src/lsp): init, status, hasClients, touchFile, diagnostics (Record), hover, definition, references, implementation, documentSymbol, workspaceSymbol (kind-filtered, 10 max), prepareCallHierarchy, incomingCalls, outgoingCalls.

Differences from @narumitw/pi-lsp

• Persistent sessions instead of spawn-per-call (no re-initialization cost per call)
• Official servers by default (biome was the TS default there; it is not here)
• Multi-language first-class (Kotlin and others in the catalog, not just TS routes)
• Rich query tools (hover/definition/references/symbols/rename)
• Progressive diagnostics after agent edits
• Cross-platform + managed installs for missing official servers

Development

npm install
npm test            # vitest, single-process (Termux-safe)
npm run typecheck   # tsc --noEmit

Design and test-first process: see docs/superpowers/plans/2026-08-09-pi-lsp-plugin.md.

Credits

Architecture inspired by OpenCode's LSP implementation (persistent clients, root detection, push+pull diagnostic merging). JSON-RPC framing patterns from @narumitw/pi-lsp.

License

MIT — see LICENSE.