LSP Integration Skill

You are an expert in leveraging Language Server Protocol (LSP) for semantic code understanding. LSP provides 100x faster and more accurate code exploration than text-based grep searches.

Overview

LSP servers understand code semantically - they know about types, symbols, references, and relationships between code elements. This enables precise navigation and refactoring that text search cannot achieve.

Supported Languages

Language LSP Server Install

TypeScript/JavaScript typescript-language-server

npm install -g typescript-language-server typescript

Python python-lsp-server (pylsp) pip install python-lsp-server

Go gopls

go install golang.org/x/tools/gopls@latest

Rust rust-analyzer

Via rustup or standalone

Java jdtls

Eclipse JDT Language Server

C# omnisharp

.NET SDK

Key Operations

1. Go to Definition

Navigate to where a symbol is defined.

Using TypeScript language server

npx ts-node --eval " const ts = require('typescript'); // Find definition of symbol at position "

Use case: "Where is this function defined?" → Find exact location in codebase.

2. Find All References

Find every place a symbol is used.

Critical for refactoring: Before renaming or changing a function, ALWAYS find all references to understand impact.

Find all usages of a function/variable/class

LSP tracks semantic references, not just text matches

Use case: "What will break if I change this interface?" → Find all implementations and usages.

3. Document Symbols

Get structured view of all symbols in a file.

Use case: "What functions/classes are in this file?" → Get hierarchy without parsing.

4. Hover Information

Get type information and documentation for any symbol.

Use case: "What type does this variable have?" → Get inferred or declared type.

5. Diagnostics

Get compilation errors and warnings.

Use case: "Are there any type errors?" → Real-time error checking.

When to Use LSP vs Grep

Task Use LSP Use Grep

Find function definition ✅ Precise ⚠️ May find wrong match

Find all references ✅ Semantic ⚠️ Misses renamed imports

Search for text pattern ❌ Not designed for this ✅ Fast text search

Understand type hierarchy ✅ Full inheritance chain ❌ Cannot determine

Check for type errors ✅ Compiler-accurate ❌ Impossible

Find files by name ❌ Overkill ✅ Use Glob

Best Practices

1. Always Use findReferences Before Refactoring

❌ WRONG: Grep for function name → rename → hope nothing breaks ✅ RIGHT: LSP findReferences → understand all usages → safe rename

2. Use goToDefinition Instead of Grep

❌ WRONG: grep -r "function processOrder" . ✅ RIGHT: LSP goToDefinition → exact location, handles imports/exports

3. Combine with Explore Agent

For complex exploration tasks, combine LSP operations with the Explore agent:

1. LSP: Find all references to deprecated function
2. Explore: Understand migration patterns in codebase
3. LSP: Navigate to each usage for refactoring

TypeScript/JavaScript Specific

Setup

Install globally

npm install -g typescript-language-server typescript

Verify installation

typescript-language-server --version

Common Operations

Find where interface is implemented:

// LSP findReferences on interface → shows all implementing classes

Check type at position:

// LSP hover → shows inferred type, even for complex generics

Find unused exports:

// LSP diagnostics + findReferences → exports with 0 references

Python Specific

Setup

pip install python-lsp-server

Optional: Add type checking

pip install pylsp-mypy

Common Operations

Find class hierarchy:

LSP can show base classes and subclasses

Check import resolution:

LSP resolves imports even with complex init.py structures

Integration with SpecWeave

In CLAUDE.md (already documented)

LSP operations are recommended in the SpecWeave workflow:

• Use findReferences before any refactoring

• Use goToDefinition for code navigation

• Use getDiagnostics to check for errors

Workflow Example

• Before implementing: Use LSP to understand existing code structure

• During implementation: Use diagnostics to catch errors early

• Before commit: Use findReferences to verify no broken usages

• Code review: Use LSP to trace data flow through system

Troubleshooting

LSP Server Not Starting

Check if server is installed

which typescript-language-server which pylsp which gopls

Check for initialization errors

typescript-language-server --stdio 2>&1 | head -20

Slow Performance

• Exclude node_modules and build directories

• Ensure tsconfig.json or equivalent is properly configured

• Increase memory limits for large projects

Missing References

• Ensure project is properly typed

• Check that all dependencies have type definitions

• Verify language server has indexed the project

Token Budget

• LSP setup instructions: 200-300 tokens

• Single operation explanation: 100-200 tokens

• Full workflow: 400-600 tokens

NEVER exceed 2000 tokens per response!