lsp-integration

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

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

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

1. Before implementing: Use LSP to understand existing code structure
2. During implementation: Use diagnostics to catch errors early
3. Before commit: Use findReferences to verify no broken usages
4. 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!