pi-lsp-extension

A pi coding agent extension that integrates Language Server Protocol (LSP) servers, giving the LLM access to the same language intelligence that powers your IDE.

Tools

LSP servers start lazily — they only spin up when a tool is first used on a file of that language. For slow servers (e.g. jdtls), you can auto-start them on session launch.

Auto-diagnostics

After a successful write or edit, if an LSP server is already running for that file type, the extension automatically appends compilation errors to the tool result. This gives the LLM immediate feedback without requiring a separate lsp_diagnostics call.

• Scoped to the single changed file (no workspace-wide noise)
• Only errors, max 10 lines — keeps context lean
• Only fires when a server is already running (no lazy startup)

Installation

pi install npm:pi-lsp-extension
# or straight from GitHub
pi install git:github.com/samfoy/pi-lsp-extension

For local development:

git clone https://github.com/samfoy/pi-lsp-extension.git
cd pi-lsp-extension
npm install
npm run build        # bundles src/ into dist/ (committed, so git installs need no build)
pi -e .              # or: pi install ./

Running from source (pi -e ./src/index.ts) also needs npm run build first: the shared daemon always runs as dist/lsp-daemon.js, so rebuild after changing src/lsp-daemon.ts.

npm run check typechecks, npm test runs the test suites. Rebuild and commit dist/ with any source change; CI fails if it is stale.

Supported Languages

Install the language server you need, then it works automatically:

Add more at runtime:

/lsp-config ruby solargraph stdio
/lsp-config lua lua-language-server

Commands

How it Works

1. Lazy startup — servers start on first tool use for a file type (or eagerly via .pi-lsp.json)
2. Tree-sitter fallback — when no LSP server is running, tools like lsp_diagnostics, lsp_hover, lsp_definition, and lsp_symbols fall back to tree-sitter for syntax errors, signatures, and symbol extraction
3. File sync — pi's read/write/edit operations are automatically synced to the LSP via didOpen/didChange, with LRU eviction (didClose) after 100 tracked files
4. Diagnostics cache — the server pushes diagnostics asynchronously; tools read from a local cache
5. Auto-diagnostics — errors are appended to write/edit results when a server is running
6. Shared daemons — in supported workspaces, LSP servers run as background daemons shared across pi sessions

Lombok Support (Java)

If your Java project uses Lombok, jdtls needs the Lombok agent jar to understand generated code. The extension resolves the jar in this order:

1. /lsp-lombok command — set the path at runtime:

   /lsp-lombok /path/to/lombok.jar

2. LOMBOK_JAR environment variable — set before starting pi:

   export LOMBOK_JAR=/path/to/lombok.jar
   pi

3. Auto-detection — in Brazil workspaces, the extension searches env/Lombok-*/runtime/lib/ and env/gradle-cache-2/ automatically.

Run /lsp-lombok with no arguments to see which jar is currently configured.

Java Import Exclusions

jdtls always receives java.import.exclusions: jdtls's own defaults (**/node_modules/**, **/.metadata/**, **/archetype-resources/**, **/META-INF/maven/**) plus the generated dirs **/.bemol/** and **/.gradle/**.

To change the list, set initializationOptions for java in .pi-lsp.json. It replaces the extension's Java defaults, so list every pattern you want to keep. Lombok still works, because its -javaagent flag goes on the jdtls command line.

{
  "servers": {
    "java": {
      "command": "jdtls",
      "initializationOptions": {
        "settings": {
          "java.import.exclusions": [
            "**/node_modules/**",
            "**/.metadata/**",
            "**/archetype-resources/**",
            "**/META-INF/maven/**",
            "**/generated-sources/**"
          ]
        }
      }
    }
  }
}

jdtls matches these globs against absolute paths, including the workspace root. A pattern like **/build/** therefore also matches every project when the workspace itself sits under a build/ directory, and jdtls imports nothing.

Project Config

Create a .pi-lsp.json file in your project root to configure LSP behavior per-project:

{
  "autoStart": ["java", "typescript"],
  "lombokJar": "auto",
  "autoInjectDiagnostics": ["typescript"],
  "servers": {
    "python": { "command": "pylsp", "args": [] }
  }
}

The config file is loaded once at session start. Changes require restarting the pi session.

Example for a Java Brazil workspace:

{
  "autoStart": ["java"],
  "lombokJar": "auto"
}

This starts jdtls as soon as the session begins, so by the time you need lsp_diagnostics or lsp_hover, the server is already warm.

Architecture

src/
├── index.ts              # Extension entry point, .pi-lsp.json config loader
├── lsp-client.ts         # JSON-RPC client (stdio + socket modes)
├── lsp-manager.ts        # Server lifecycle, per-language instances
├── file-sync.ts          # didOpen/didChange tracking
├── lsp-daemon.ts         # Background daemon for shared servers (built to dist/lsp-daemon.js)
├── resolve-provider.ts   # LSP vs tree-sitter provider selection
├── workspace-provider.ts # Workspace detection / daemon state interface
├── shared/
│   ├── constants.ts      # Skip dirs, file size limits
│   ├── debug.ts          # Debug logger (PI_LSP_DEBUG=1)
│   ├── format.ts         # Location formatting utilities
│   ├── language-map.ts   # File extension → language ID mapping
│   └── timing.ts         # Timing constants
├── tree-sitter/
│   ├── parser-manager.ts # WASM parser loading and caching
│   ├── pattern-compiler.ts # Metavariable pattern → AST matcher
│   ├── search-engine.ts  # Structural search over files
│   ├── rewrite-engine.ts # Structural find-and-replace
│   ├── symbol-extractor.ts # Per-language symbol extraction
│   └── workspace-index.ts # Project-wide symbol index
└── tools/
    ├── diagnostics.ts
    ├── hover.ts
    ├── definition.ts
    ├── references.ts
    ├── symbols.ts
    ├── rename.ts
    ├── completions.ts
    ├── code-overview.ts
    ├── code-search.ts
    └── code-rewrite.ts

Tips

• Position parameters are 1-indexed (line 1, column 1 = first character)
• lsp_rename returns a preview — the LLM uses edit/write to apply changes
• Use /lsp-restart java after changing Lombok config — jdtls needs a full restart to pick up -javaagent changes
• Set PI_LSP_DEBUG=1 to enable debug logging for troubleshooting
• The extension adds a system prompt guideline nudging the LLM to check diagnostics after edits

License

MIT © 2026 Sam Painter