LSP Auto-Configuration Skill

Manual control and troubleshooting for Language Server Protocol (LSP) configuration.

Important: LSP is Configured Automatically

You probably don't need this skill! LSP is configured automatically when you run amplihack claude.

When amplihack launches Claude Code, it automatically:

Detects programming languages in your project
Sets ENABLE_LSP_TOOL=1 environment variable
Installs required LSP plugins via Claude Code plugin marketplace
Configures project-specific settings in .env

You'll see: 📡 LSP: Detected 3 language(s): python, javascript... when amplihack starts Claude Code.

When to Use This Skill

Use /lsp-setup only when you need to:

Check Status: Verify LSP configuration is working (/lsp-setup --status-only)
Troubleshoot Issues: Diagnose why code intelligence isn't working
Force Reconfiguration: Rebuild LSP config after manual changes (/lsp-setup --force)
Add New Languages: Configure LSP for newly added languages

Don't use this skill if: LSP is already working! The automatic setup handles 99% of cases.

Overview

The LSP Setup skill provides manual control over the same LSP auto-configuration that happens automatically at launch. It supports 16 popular programming languages out of the box and gives you direct access to configuration, status checking, and troubleshooting.

What LSP Provides to You

When LSP is properly configured, Claude Code gains powerful code intelligence capabilities that enhance the AI's understanding of your codebase:

Real-Time Code Intelligence

Type Information - Claude can see the exact types of variables, functions, and classes:

# Claude can hover over 'user' and see: Type: User (class from models.py)
user = get_current_user()

Go to Definition - Claude can jump to where symbols are defined:

# Claude can navigate from 'authenticate()' call to its definition in auth.py
result = authenticate(credentials)

Code Diagnostics - Claude receives real-time error detection from LSP servers:

# Pyright reports: "Set" is not accessed
from typing import List, Set  # Claude sees this warning

How Claude Uses LSP

Better Code Understanding - Instead of guessing types and behavior, Claude gets precise information from LSP servers about:

Function signatures and return types
Class hierarchies and inheritance
Import paths and module structure
Errors and warnings before runtime

Smarter Suggestions - With LSP data, Claude provides:

Accurate refactoring recommendations
Type-safe code completions
Precise error fixes
Context-aware code generation

Example Workflow:

You: "Fix the type error in user_service.py"

Without LSP: Claude reads the file, guesses at types, may miss subtle issues

With LSP: Claude receives diagnostic:
  Line 42: Expected type 'User | None', got 'str'
  → Claude provides exact fix based on actual type information

What You'll Notice

After /lsp-setup configures your project:

More Accurate Responses - Claude's code suggestions match your actual types and APIs
Faster Debugging - Claude sees the same errors your IDE would show
Better Refactoring - Claude can safely rename variables across files using LSP references
Improved Navigation - Claude can find definitions, usages, and implementations precisely

Important Note

LSP enhances Claude's capabilities behind the scenes. You don't interact with LSP directly - it makes Claude smarter about your code automatically.

When to Use This Skill

Use /lsp-setup when you:

Start working on a new project in Claude Code
Add a new programming language to an existing project
Experience missing or incorrect code intelligence features
Want to verify your LSP configuration is correct
Need to troubleshoot LSP server connection issues

How It Works

LSP Architecture - Three Layers

Claude Code's LSP system uses a three-layer architecture that must all be configured for LSP features to work:

Layer 1: System LSP Binaries (User-installed)

LSP server executables installed on your system via npm, brew, rustup, etc.
Example: npm install -g pyright installs the Pyright LSP server binary
These are the actual language analysis engines

Layer 2: Claude Code LSP Plugins (Installed via cclsp)

Claude Code plugins that connect to Layer 1 binaries
Installed using: npx cclsp install <server-name>
The cclsp tool uses the claude-code-lsps plugin marketplace
These act as bridges between Claude Code and LSP servers

Layer 3: Project Configuration (.env file)

Project-specific settings: virtual environments, project roots, etc.
Must include ENABLE_LSP_TOOL=1 to activate LSP features
Stored in .env at project root

Important: cclsp and claude-code-lsps work together. cclsp is the installation tool, claude-code-lsps is the plugin marketplace it uses. They are complementary, not alternatives.

The Skill's 4-Phase Process

The /lsp-setup skill automates the workflow from npx cclsp@latest setup:

Phase 1: Language Detection

Scans your project directory to identify programming languages based on file extensions and framework markers. Detects 16 languages including Python, TypeScript, JavaScript, Rust, Go, Java, and more.

Phase 2: LSP Configuration

Generates the appropriate LSP server configuration for each detected language. Checks if:

System LSP binaries are installed (Layer 1)
Claude Code plugins are installed (Layer 2)

Provides installation guidance if either is missing. NEVER auto-installs - user has full control.

Phase 3: Project Configuration

Creates or updates .env file with project-specific LSP settings (Layer 3):

Workspace-specific options (Python virtual environments, Node.js project roots, etc.)
ENABLE_LSP_TOOL=1 (required for LSP features to activate)

Phase 4: Verification

Tests each LSP server connection and reports status. Provides actionable guidance for any configuration issues.

Usage

Basic Usage

/lsp-setup

Detects all languages in your project and configures LSP servers automatically.

Check Status Only

/lsp-setup --status-only

Reports current LSP configuration and server availability without making changes.

Force Reconfiguration

/lsp-setup --force

Regenerates LSP configuration even if valid configuration already exists.

Specific Languages

/lsp-setup --languages python,typescript

Configures LSP servers only for specified languages.

Manual Plugin Management

If you need to manage Claude Code LSP plugins directly, use the cclsp command:

# Install a plugin (Layer 2)
npx cclsp install pyright

# List installed plugins
npx cclsp list

# Remove a plugin
npx cclsp remove pyright

# Full setup workflow (what /lsp-setup automates)
npx cclsp@latest setup

The /lsp-setup skill automates the npx cclsp@latest setup workflow, adding intelligent language detection and project-specific configuration.

Supported Languages

Language	LSP Server	System Binary Installation (Layer 1)	Claude Code Plugin (Layer 2)
Python	pyright	`npm install -g pyright`	`npx cclsp install pyright`
TypeScript	vtsls	`npm install -g @vtsls/language-server`	`npx cclsp install vtsls`
JavaScript	vtsls	`npm install -g @vtsls/language-server`	`npx cclsp install vtsls`
Rust	rust-analyzer	`rustup component add rust-analyzer`	`npx cclsp install rust-analyzer`
Go	gopls	`go install golang.org/x/tools/gopls@latest`	`npx cclsp install gopls`
Java	jdtls	Download from eclipse.org/jdtls	`npx cclsp install jdtls`
C/C++	clangd	`brew install llvm` (macOS) / `apt install clangd` (Linux)	`npx cclsp install clangd`
C#	omnisharp	Download from omnisharp.net	`npx cclsp install omnisharp`
Ruby	ruby-lsp	`gem install ruby-lsp`	`npx cclsp install ruby-lsp`
PHP	phpactor	`composer global require phpactor/phpactor`	`npx cclsp install phpactor`
Bash	bash-language-server	`npm install -g bash-language-server`	`npx cclsp install bash-language-server`
YAML	yaml-language-server	`npm install -g yaml-language-server`	`npx cclsp install yaml-language-server`
JSON	vscode-json-languageserver	`npm install -g vscode-json-languageserver`	`npx cclsp install vscode-json-languageserver`
HTML	vscode-html-languageserver	`npm install -g vscode-html-languageserver`	`npx cclsp install vscode-html-languageserver`
CSS	vscode-css-languageserver	`npm install -g vscode-css-languageserver`	`npx cclsp install vscode-css-languageserver`
Markdown	marksman	`brew install marksman` (macOS) / Download from GitHub	`npx cclsp install marksman`

Note: Both Layer 1 (system binary) and Layer 2 (Claude Code plugin) must be installed for LSP features to work.

Example: Python Project Setup

$ cd my-python-project
$ /lsp-setup

[LSP Setup] Detecting languages...
✓ Found: Python (23 files)
✓ Found: YAML (2 files)
✓ Found: Markdown (1 file)

[LSP Setup] Configuring LSP servers...
✓ pyright: Installed at /usr/local/bin/pyright
✓ yaml-language-server: Installed at /usr/local/bin/yaml-language-server
✓ marksman: Installed at /usr/local/bin/marksman

[LSP Setup] Configuring project...
✓ Created .env with LSP configuration
✓ Detected Python virtual environment: .venv
✓ Configured pyright to use .venv/bin/python

[LSP Setup] Verifying connections...
✓ pyright: Connected (Python 3.11.5)
✓ yaml-language-server: Connected
✓ marksman: Connected

Configuration complete! LSP servers ready.

Example: Polyglot Project Setup

$ cd my-fullstack-app
$ /lsp-setup

[LSP Setup] Detecting languages...
✓ Found: TypeScript (45 files)
✓ Found: Python (12 files)
✓ Found: Rust (8 files)
✓ Found: JSON (6 files)

[LSP Setup] Configuring LSP servers...
✓ vtsls: Installed
✓ pyright: Installed
✗ rust-analyzer: Not found

[LSP Setup] Installation guidance:
To install rust-analyzer:
  $ rustup component add rust-analyzer

Would you like to continue with available servers? [Y/n] y

[LSP Setup] Configuring project...
✓ Created .env with LSP configuration
✓ Detected Node.js project root: ./frontend
✓ Detected Python project root: ./backend
✓ Detected Rust workspace: ./services

[LSP Setup] Verifying connections...
✓ vtsls: Connected (TypeScript 5.3.3)
✓ pyright: Connected (Python 3.11.5)
⚠ rust-analyzer: Skipped (not installed)

Configuration complete! 2/3 LSP servers ready.
Run `rustup component add rust-analyzer` to enable Rust support.

How to Verify LSP is Working

After running /lsp-setup, here's how to confirm LSP is providing code intelligence to Claude:

Method 1: Check for Diagnostics

Ask Claude to analyze a file with intentional errors:

You: "What issues do you see in src/main.py?"

If LSP is working: Claude will report specific diagnostics from Pyright
  → "Line 15: 'name' is not accessed"
  → "Line 23: Expected type 'int', got 'str'"

If LSP is NOT working: Claude only sees what's in the file content
  → Generic observations about code style
  → No specific type errors or warnings

Method 2: Request Type Information

Ask Claude about types in your code:

You: "What's the type of the 'user' variable in auth.py line 42?"

If LSP is working: Claude provides exact type from LSP
  → "Type: User | None (from models.User)"

If LSP is NOT working: Claude guesses based on context
  → "It appears to be a User object based on the code"

Method 3: Test Navigation

Ask Claude to find definitions:

You: "Where is the authenticate() function defined?"

If LSP is working: Claude uses LSP goToDefinition
  → "Defined in src/auth/service.py:156"

If LSP is NOT working: Claude searches file contents
  → "I found it by searching for 'def authenticate'"

Method 4: Check Status Command

Run the status check:

/lsp-setup --status-only

Expected Output (LSP Working):

[LSP Setup] Configuration Status:

✓ Python (pyright): Connected
  - System Binary: /usr/local/bin/pyright-langserver
  - Plugin: Installed and active
  - Project Config: .env configured with ENABLE_LSP_TOOL=1

✓ TypeScript (vtsls): Connected
  - System Binary: /usr/local/bin/vtsls
  - Plugin: Installed and active
  - Project Config: .env configured with ENABLE_LSP_TOOL=1

Overall Status: ✓ All LSP servers ready (2/2)

Problem Output (LSP NOT Working):

[LSP Setup] Configuration Status:

✗ Python (pyright): Not Connected
  - System Binary: Not found
  - Plugin: Not installed
  - Project Config: Missing ENABLE_LSP_TOOL=1

Issue: Run 'npm install -g pyright' and 'npx cclsp install pyright'

What Success Looks Like

When LSP is working properly, you'll notice:

Claude mentions specific line numbers when discussing errors
Claude provides exact types instead of guessing
Claude sees warnings/errors before code runs (like your IDE does)
Claude can navigate code structure using LSP's understanding

What Failure Looks Like

When LSP is NOT working, you'll notice:

Claude only sees file contents - no type information or diagnostics
Claude makes educated guesses about types and behavior
Claude doesn't mention errors until you run the code
Claude searches text instead of using semantic understanding

Troubleshooting

Issue: LSP server not found

Symptom: "rust-analyzer: Not found" during configuration

Solution: Install the LSP server using the provided installation command

$ rustup component add rust-analyzer
$ /lsp-setup --force  # Reconfigure after installation

Issue: LSP server crashes on startup

Symptom: "pyright: Connection failed" during verification

Solution: Check LSP server logs and verify installation

# Check if server is properly installed
$ which pyright
/usr/local/bin/pyright

# Test server manually
$ pyright --version
pyright 1.1.332

# Check Claude Code LSP logs
$ cat ~/.claude-code/lsp-logs/pyright.log

Issue: Wrong Python interpreter used

Symptom: Import errors despite packages being installed in virtual environment

Solution: Verify .env configuration points to correct Python interpreter

# Check current configuration
$ cat .env | grep PYTHON

# Should show:
LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python

# If incorrect, update manually or run:
$ /lsp-setup --force

Issue: TypeScript project not detected

Symptom: No TypeScript LSP configuration despite .ts files present

Solution: Ensure tsconfig.json exists in project root

# Create minimal tsconfig.json
$ cat > tsconfig.json << EOF
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true
  }
}
EOF

$ /lsp-setup --force

Issue: Multiple Python versions causing conflicts

Symptom: "Module not found" errors when LSP server uses wrong Python version

Solution: Explicitly set Python interpreter in .env

# Edit .env manually
LSP_PYTHON_INTERPRETER=/usr/bin/python3.11

# Or activate the correct virtual environment before running
$ source .venv/bin/activate
$ /lsp-setup --force

Configuration Files

`.env` (Project Root)

The skill creates or updates .env with LSP-specific configuration:

# LSP Configuration - Auto-generated by /lsp-setup
ENABLE_LSP_TOOL=1  # REQUIRED: Activates LSP features in Claude Code

# Project-specific settings (Layer 3)
LSP_PYTHON_INTERPRETER=/path/to/.venv/bin/python
LSP_NODE_PROJECT_ROOT=/path/to/frontend
LSP_RUST_WORKSPACE=/path/to/services
LSP_GO_MODULE=/path/to/go.mod

# Language Server Paths (auto-detected)
LSP_PYRIGHT_PATH=/usr/local/bin/pyright
LSP_VTSLS_PATH=/usr/local/bin/vtsls
LSP_RUST_ANALYZER_PATH=/usr/local/bin/rust-analyzer

Critical: ENABLE_LSP_TOOL=1 must be present for LSP features to work. Without it, LSP servers won't be activated.

Claude Code LSP Configuration

The skill automatically updates Claude Code's LSP configuration. No manual editing required.

Integration with Claude Code

Once configured, Claude Code automatically:

Provides code completion based on project context
Shows real-time diagnostics (errors, warnings)
Enables "Go to Definition" navigation
Offers inline documentation on hover
Suggests intelligent refactorings

Best Practices

Run at project start: Configure LSP servers when you first open a project
Update after adding languages: Rerun /lsp-setup when adding new language files
Commit .env: Include LSP configuration in version control for team consistency
Verify after installation: Use --status-only to check server availability
Keep servers updated: Regularly update LSP servers to latest versions

Technical Details

Skill Type: Interactive command-driven workflow

Dependencies: None (pure skill, no external packages)

Execution Time: 2-10 seconds depending on project size

Persistence: Configuration stored in .env and Claude Code settings

Supported Platforms: macOS, Linux, WSL

Related Skills

environment-setup - General development environment configuration
dependency-manager - Package and dependency management
project-init - New project initialization

Maintenance

The LSP Setup skill requires no manual maintenance. It automatically adapts to your project structure and detects language changes on each run.

To update LSP server definitions or add new languages, see the developer documentation in README.md.

Execution Instructions (For Claude Code)

When this skill is activated via /lsp-setup or activation keywords, execute the following workflow:

Phase 1: Language Detection

from pathlib import Path
from lsp_setup import LanguageDetector

# Detect languages in current project
detector = LanguageDetector()
project_root = Path.cwd()
languages = detector.detect_languages(project_root)

# Report findings
print(f"Detected {len(languages)} language(s):")
for lang in languages:
    print(f"  - {lang.language}: {lang.file_count} files")

Phase 2: Check Current Status

from lsp_setup import StatusTracker

# Get current LSP setup status
language_names = [lang.language for lang in languages]
tracker = StatusTracker(project_root, language_names)
status = tracker.get_full_status()

# Show status
print(tracker.generate_user_guidance())

Phase 3: Configure LSP (If Needed)

from lsp_setup import LSPConfigurator

# Configure .env file
configurator = LSPConfigurator(project_root)

# Enable LSP
if not configurator.is_lsp_enabled():
    configurator.enable_lsp()
    print("✓ Enabled LSP in .env")

Phase 4: Install Plugins (If Needed)

from lsp_setup import PluginManager

# Install Claude Code plugins for detected languages
manager = PluginManager()

# Check prerequisites
if not manager.check_npx_available():
    print("⚠ npx not found. Install Node.js first:")
    print("  macOS: brew install node")
    print("  Linux: sudo apt install nodejs")
    exit(1)

# Install plugins for languages with missing Layer 2
for lang_name in language_names:
    layer_2_status = status["layer_2"][lang_name]
    if not layer_2_status["installed"]:
        print(f"Installing {lang_name} plugin...")
        success = manager.install_plugin(lang_name)
        if success:
            print(f"✓ {lang_name} plugin installed")
        else:
            print(f"✗ Failed to install {lang_name} plugin")
            print(f"  {layer_2_status.get('install_guide', 'See docs')}")

Phase 5: Final Status Report

# Recheck status after installation
final_status = tracker.get_full_status()

if final_status["overall_ready"]:
    print("\n✅ LSP setup complete! All layers configured.")
else:
    print("\n⚠ LSP partially configured. Next steps:")
    print(tracker.generate_user_guidance())

Command-Line Arguments (Optional)

Support these arguments if provided by user:

--status-only: Skip installation, just report current status
--force: Reinstall all plugins even if already installed
--languages <lang1,lang2>: Configure only specific languages
--dry-run: Show what would be done without making changes

lsp-setup

LSP Auto-Configuration Skill

Important: LSP is Configured Automatically

When to Use This Skill

Overview

What LSP Provides to You

Real-Time Code Intelligence

How Claude Uses LSP

What You'll Notice

Important Note

When to Use This Skill

How It Works

LSP Architecture - Three Layers

The Skill's 4-Phase Process

Phase 1: Language Detection

Phase 2: LSP Configuration

Phase 3: Project Configuration

Phase 4: Verification

Usage

Basic Usage

Check Status Only

Force Reconfiguration

Specific Languages

Manual Plugin Management

Supported Languages

Example: Python Project Setup

Example: Polyglot Project Setup

How to Verify LSP is Working

Method 1: Check for Diagnostics

Method 2: Request Type Information

Method 3: Test Navigation

Method 4: Check Status Command

What Success Looks Like

What Failure Looks Like

Troubleshooting

Issue: LSP server not found

Issue: LSP server crashes on startup

Issue: Wrong Python interpreter used

Issue: TypeScript project not detected

Issue: Multiple Python versions causing conflicts

Configuration Files

.env (Project Root)

Claude Code LSP Configuration

Integration with Claude Code

Best Practices

Technical Details

Related Skills

Maintenance

Execution Instructions (For Claude Code)

Phase 1: Language Detection

Phase 2: Check Current Status

Phase 3: Configure LSP (If Needed)

Phase 4: Install Plugins (If Needed)

Phase 5: Final Status Report

Command-Line Arguments (Optional)

`.env` (Project Root)