LSP Code Analysis

IMPORTANT: PREREQUISITE

You MUST run the update script to check for updates before using this skill.

Before any LSP operations, you MUST first run lsp server start <project_path> to verify project support.

IF YOU DO NOT PERFORM THESE STEPS, YOU ARE NOT ALLOWED TO USE THIS SKILL.

Abstract

This document specifies the operational requirements and best practices for the lsp-code-analysis skill. It provides a semantic interface to codebase navigation and analysis via the Language Server Protocol (LSP).

Overview

You SHOULD use the lsp CLI tool for semantic code navigation and analysis, and it SHOULD be preferred over read or grep for most code understanding tasks.

• Semantic navigation: Jump to definitions, find references, locate implementations - understands code structure, not just text patterns.
• Language-aware: Distinguishes between variables, functions, classes, types - eliminates false positives from text search.
• Cross-file intelligence: Trace dependencies, refactor safely across entire codebase - knows what imports what.
• Type-aware: Get precise type information, signatures, documentation - without reading implementation code.

Tool Selection

Task	Traditional Tool	Recommended LSP Command
Find Definition	grep, read	definition
Find Usages	grep -r	reference
Understand File	read	outline
View Docs/Types	read	doc
Refactor	sed	See Refactoring Guide

Guideline: Agents SHOULD prioritize LSP commands for code navigation and analysis. Agents MAY use read or grep ONLY when semantic analysis is not applicable (e.g., searching for comments or literal strings).

Commands

All commands support -h or --help.

Locating Symbols

Most commands use a unified Locate String syntax via the -L or --locate option.

Syntax: <file_path>[:<scope>][@<find>]

For Monorepo or Multi-root workspaces, see monorepo.md.

Scope Formats:

• <line>: Single line number (e.g., 42).
• <start>,<end>: Line range with comma (e.g., 10,20).
• <start>-<end>: Line range with dash (e.g., 10-20).
• <symbol_path>: Symbol path with dots (e.g., MyClass.my_method).

Find Pattern (@<find>):

The optional @<find> suffix narrows the target to a text pattern within the selected scope:

• The scope is determined by <scope> (line/range/symbol). If no <scope> is given, the entire file is the scope.
• <find> is matched in a whitespace-insensitive way: differences in spaces, tabs, and newlines are ignored.
• You MAY include the cursor marker <|> inside <find> to specify the exact position of interest within the match (for example, on a variable name, keyword, or operator).
• If <find> is omitted, the command uses the start of the scope (or a tool-specific default) as the navigation target.

Cursor Marker (<|>):

The <|> marker indicates the exact position for symbol resolution. Use it within the find pattern to point to a specific element (e.g., user.<|>name to target the name property).

Examples:

• foo.py@self.<|> - Find self. in entire file, position at cursor marker
• foo.py:42@return <|>result - Find return result on line 42, position at cursor marker
• foo.py:10,20@if <|>condition - Find if condition in lines 10-20, position at cursor marker
• foo.py:MyClass.my_method@self.<|> - Find self. within MyClass.my_method, position at cursor marker
• foo.py:MyClass - Target the MyClass symbol directly

Agents MAY use lsp locate <string> with the -c or --check flag to verify if the target exists in the file and view its context before running other commands.

# Verify location exists
lsp locate "main.py:42@process_data" --check

Outline: File Structure

Get hierarchical symbol structure without reading implementation.

# Get main symbols (classes, functions, methods)
lsp outline <file_path>

# Get all symbols including variables and parameters
lsp outline <file_path> --all

Agents SHOULD use outline before reading files to avoid unnecessary context consumption.

Definition: Navigate to Source

Navigate to where symbols are defined.

# Jump to where User.get_id is defined
lsp definition -L "models.py:User.get_id"

# Find where an imported variable comes from
lsp definition -L "main.py:42@config<|>"

# Find declaration (e.g., header files, interface declarations)
lsp definition -L "models.py:25" --decl

# Find the class definition of a variable's type
lsp definition -L "models.py:30@user<|>" --type

Reference: Find All Usages

Find where symbols are used or implemented.

# Find all places where logger is referenced
lsp reference -L "main.py:MyClass.run@logger"

# Find all concrete implementations of an interface/abstract class
lsp reference -L "api.py@IDataProvider" --impl

# Get more surrounding code context for each reference
lsp reference -L "app.py:10@TestClass" --context-lines 5

# Limit results for large codebases
lsp reference -L "utils.py:helper" --max-items 50 --start-index 0

Doc: Get Documentation

Get documentation and type information without navigating to source.

# Get docstring and type info for symbol at line 42
lsp doc -L "main.py:42"

# Get API documentation for process_data function
lsp doc -L "models.py@process_data<|>"

Agents SHOULD prefer doc over read when only documentation or type information is needed.

Search: Global Symbol Search

Search for symbols across the workspace when location is unknown.

# Search by name (defaults to current directory)
lsp search "MyClassName"

# Search in specific workspace
lsp search "UserModel" --workspace /path/to/project

# Filter by symbol kind (can specify multiple times)
lsp search "init" --kind function --kind method

# Limit and paginate results for large codebases
lsp search "Config" --max-items 10
lsp search "User" --max-items 20 --start-index 0

Agents SHOULD use --kind to filter results and reduce noise.

Refactoring Operations

Read Refactoring Guide for rename, extract, and other safe refactoring operations.

Symbol: Get Complete Symbol Code

Get the full source code of the symbol containing a location.

# Get complete code of the function/class at line 15
lsp symbol -L "main.py:15"

# Get full UserClass implementation
lsp symbol -L "utils.py@UserClass<|>"

# Get complete method implementation
lsp symbol -L "models.py:User.validate"

Response includes: symbol name, kind (class/function/method), range, and complete source code.

Agents SHOULD use symbol to read targeted code blocks instead of using read on entire files.

Server: Manage Background Servers

The background manager starts automatically. Manual control is OPTIONAL.

# List running servers (default)
lsp server
lsp server list

# Start server for a project
lsp server start <path>

# Stop server for a project
lsp server stop <path>

Best Practices

General Workflows

Understanding Unfamiliar Code

The RECOMMENDED sequence for exploring new codebases:

# Step 1: Start with outline - Get file structure without reading implementation
lsp outline <file_path>

# Step 2: Inspect signatures - Use doc to understand API contracts
lsp doc -L "<file_path>:<symbol_name>"

# Step 3: Navigate dependencies - Follow definition chains
lsp definition -L "<file_path>:<symbol_name>"

# Step 4: Map usage - Find where code is called with reference
lsp reference -L "<file_path>:<symbol_name>"

Debugging Unknown Behavior

# Step 1: Locate symbol definition workspace-wide
lsp search "<symbol_name>"

# Step 2: Verify implementation details
lsp definition -L "<file_path>:<symbol_name>"

# Step 3: Trace all callers to understand invocation context
lsp reference -L "<file_path>:<symbol_name>"

Finding Interface Implementations

# Step 1: Locate interface definition
lsp search "IUserService" --kind interface

# Step 2: Find all implementations
lsp reference -L "src/interfaces.py:IUserService" --impl

Tracing Data Flow

# Step 1: Find where data is created
lsp search "UserDTO" --kind class

# Step 2: Find where it's used
lsp reference -L "models.py:UserDTO"

# Step 3: Check transformations
lsp doc -L "transform.py:map_to_dto"

Understanding Type Hierarchies

# Step 1: Get class outline
lsp outline models.py

# Step 2: Find subclasses (references to base)
lsp reference -L "models.py:BaseModel"

# Step 3: Check type definitions
lsp definition -L "models.py:BaseModel" --type

Performance Tips

# Use outline instead of reading entire files
lsp outline large_file.py  # Better than: read large_file.py

# Use symbol paths for nested structures (more precise than line numbers)
lsp definition -L "models.py:User.Profile.validate"

# Limit results in large codebases
lsp search "User" --max-items 20

# Use doc to understand APIs without navigating to source
lsp doc -L "api.py:fetch_data"  # Get docs/types without jumping to definition

# Verify locate strings if commands fail
lsp locate "main.py:42@process<|>" --check

Domain-Specific Guides

For specialized scenarios, see:

• Monorepo: monorepo.md
• Frontend: bp_frontend.md
• Backend: bp_backend.md