Semantic code analysis via LSP. Navigate code (definitions, references, implementations), search symbols, preview refactorings, and get file outlines. Use for exploring unfamiliar codebases or performing safe refactoring.

LSP Code Analysis IMPORTANT: PREREQUISITE To use this skill, you MUST follow these steps: 1. Check for updates : Run the [update script](scripts/update.sh) to ensure you are using the latest version of the tool. 2. Verify project support : Run lsp server start <project path to start the LSP server and confirm the project is supported. 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, analysis and refactoring via the Language Server Protocol (LSP). Overview You are provided with lsp CLI tool for semantic code navigation and analysis. It SHOULD be preferred over read or grep for most code understanding tasks. Usages: 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 Guideline : You 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). Task Traditional Tool Recommended LSP Command Find Definition grep , read [ definition ]( definition navigate to source) Find Usages grep r [ reference ]( reference find all usages) Understand File read [ outline ]( outline file structure) View Docs/Types read [ doc ]( doc get documentation) Refactor sed See [Refactoring Guide](references/refactor.md) Commands All commands support h or help . Locating Symbols Most commands use a unified locating syntax via the scope and find options. Arguments : <file path Options : scope : Narrow search to a symbol body or line range. find : Text pattern to find within the scope. Scope Formats : <line : Single line number (e.g., 42 ). <start ,<end : Line range (e.g., 10,20 ). Use 0 for end to mean till EOF (e.g., 10,0 ). <symbol path : Symbol path with dots (e.g., MyClass.my method ). Find Pattern ( find ) : The find option 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. Pattern matching is whitespace insensitive : differences in spaces, tabs, and newlines are ignored. You MAY include the cursor marker < inside the pattern 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. It represents the character immediately to its right. Use it within the find pattern to point to a specific element (e.g., user.< name to target the name property). Examples : lsp doc foo.py find "self.< " Find self. in entire file, position at the character after the dot (typically for completion or member access) lsp doc foo.py scope 42 find "return < result" Find return result on line 42, position at r of result lsp doc foo.py scope 10,20 find "if < condition" Find if condition in lines 10 20, position at c of condition lsp doc foo.py scope MyClass.my method find "self.< " Find self. within MyClass.my method , position after the dot lsp doc foo.py scope MyClass Target the MyClass symbol directly Guideline for Scope vs. Find : Use scope <symbol path (e.g., scope MyClass , scope MyClass.my method ) to target classes, functions, or methods . This is the most robust and preferred way to target symbol. Use find (often combined with scope ) to target variables or specific positions. Use this when the target is not a uniquely named symbol or when you need to pinpoint a specific usage within a code block. Agents MAY use lsp locate <file path scope <scope find <find to verify if the target exists in the file and view its context before running other commands. Pagination Use pagination for large result sets like reference or search . pagination id <ID : (Required) Unique session ID for consistent paging. max items <N : Page size. start index <N : Offset (0 based). Example : Guideline : Use pagination with a unique ID for common symbols to fetch results in manageable chunks. Increment start index using the same ID to browse. Outline: File Structure Get hierarchical symbol structure without reading implementation. Agents SHOULD use outline before reading files to avoid unnecessary context consumption. Definition: Navigate to Source Navigate to where symbols are defined. Reference: Find All Usages Find where symbols are used or implemented. Doc: Get Documentation Get documentation and type information without navigating to source. 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. Agents SHOULD use kinds to filter results and reduce noise. Symbol: Get Complete Symbol Code Get the full source code of the symbol containing a location. 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. Refactoring Operations Read [Refactoring Guide](references/refactor.md) for rename, extract, and other safe refactoring operations. Server: Manage Background Servers The background manager starts automatically. Manual control is OPTIONAL. Best Practices General Workflows Understanding Unfamiliar Code The RECOMMENDED sequence for exploring new codebases: Debugging Unknown Behavior Finding Interface Implementations Tracing Data Flow Understanding Type Hierarchies Performance Tips Domain Specific Guides For specialized scenarios, see: Monorepo : [monorepo.md](references/monorepo.md) Frontend : [bp frontend.md](references/bp frontend.md) Backend : [bp backend.md](references/bp backend.md)

lsp-code-analysis