LSP Code Intelligence

Semantic code navigation and analysis.

Current Status (v2.1.0+)

⚠️ Native LSP is BROKEN in Claude Code v2.1.0+ (Issue #17468)

Always use SpecWeave CLI until native LSP is fixed.

SpecWeave LSP CLI (Always Works)

# Find all references to a symbol (SEMANTIC, not grep!)
specweave lsp refs <file> <symbol>

# Go to definition
specweave lsp def <file> <symbol>

# Get type information (hover)
specweave lsp hover <file> <symbol>

# List all symbols in a file
specweave lsp symbols <file>

# Search workspace for symbols
specweave lsp search <query>

File Path Required

If user doesn’t specify a file path, find it first:

# Step 1: Find which file(s) contain the symbol
grep -rn --include="*.ts" "function symbolName\|class symbolName" .

# Step 2: Then use LSP on the found file
specweave lsp refs <found-file> <symbol>

Why Use SpecWeave CLI over Grep

⚠️ Never use Grep for “find references” – Grep finds TEXT matches (including comments, strings, docs). LSP finds SEMANTIC references (actual code usages only).

Workarounds for Native LSP

If you need native LSP tools:

# Option 1: Use older Claude Code version
ENABLE_LSP_TOOL=1 npx @anthropic-ai/claude-code@2.0.76

# Option 2: Use tweakcc patch
npx tweakcc --apply

Multi-Repo LSP Setup (v1.0.203+)

For umbrella projects with multiple repositories, use the interactive setup:

# Scan project and install LSP plugins interactively
specweave lsp setup

# Options:
specweave lsp setup --max 5       # Limit to top 5 languages
specweave lsp setup --min-files 10  # Min files to consider a language
specweave lsp setup --scope project # Install to .claude/settings.json
specweave lsp setup --dry-run       # Show what would be installed

What Setup Does

1. Scans all repos – Finds languages in repositories/, packages/, services/, etc.
2. Ranks by file count – Shows top languages with file counts
3. Shows implications – Restart required, startup time impact
4. Prompts for approval – User selects which plugins to install
5. Installs plugins – Uses claude plugin install with specified scope

Scan Coverage

Scans these directories for nested repositories:

• repositories/ – Multi-repo umbrella pattern
• packages/ – Monorepo (Lerna, Nx, etc.)
• services/ – Microservices
• apps/, libs/, modules/ – Nx/Turborepo patterns

Status and Diagnostics

# Check current LSP status
specweave lsp status

# Shows:
#   - LSP env ready (ENABLE_LSP_TOOL)
#   - Detected languages
#   - Missing servers/plugins
#   - Warm-up state

Supported Languages (10 LSPs)

SpecWeave LSP supports 10 major languages via their respective language servers:

Auto-Detection

SpecWeave automatically detects which language servers to use based on project files:

How to Enable LSP in Your Project

1. Install the Language Server

# For Python projects
pip install pyright
# OR
npm install -g pyright

# For Go projects
go install golang.org/x/tools/gopls@latest

# For Rust projects
rustup component add rust-analyzer

# For C# projects
dotnet tool install -g csharp-ls

2. Run SpecWeave LSP

# It auto-detects languages!
specweave lsp refs src/file.py MyClass
specweave lsp def src/main.go HandleRequest
specweave lsp hover src/lib.rs calculate

3. Verify Setup

specweave lsp status

How SpecWeave CLI Works

Uses language-specific clients:

• TypeScript: TsServerClient (direct tsserver protocol, fastest)
• Other languages: Generic LSPClient (JSON-RPC over stdio)

Features:

1. Spawns language server directly
2. Uses native LSP protocol
3. Provides real semantic analysis
4. Works in any environment (CI/CD, Claude Code, scripts)

Project-Specific Learnings

Before starting work, check for project-specific learnings:

# Check if skill memory exists for this skill
cat .specweave/skill-memories/lsp.md 2>/dev/null || echo "No project learnings yet"

Project learnings are automatically captured by the reflection system when corrections or patterns are identified during development. These learnings help you understand project-specific conventions and past decisions.