using-serena-symbols
Guidance for using Serena's LSP-powered symbol analysis. Use when exploring codebases, finding symbol definitions, tracing references, or when grep/text search would be imprecise.
When & Why to Use This Skill
This Claude skill leverages LSP-powered code intelligence to provide accurate symbol extraction, relationship discovery, and deep cross-file analysis. It enables developers to navigate complex codebases by finding precise definitions, tracing method references, and understanding call hierarchies far more effectively than standard text searches. By understanding the semantic structure of the code, it eliminates the noise of string literals and comments, providing a high-fidelity map of any software project.
Use Cases
- Codebase Exploration: Quickly grasp the layout and entry points of an unfamiliar repository by generating high-level symbol overviews of key files.
- Impact Analysis: Trace all referencing symbols for a specific function or class to evaluate the potential side effects of a refactoring or code change.
- Precise Navigation: Locate exact class or method definitions across multiple files using pattern matching, avoiding the 'false positives' common in grep-based searches.
- Architectural Mapping: Analyze call hierarchies and cross-file dependencies to understand how different modules and services interact within a system.
- Dependency Tracing: Identify all imports and usages of specific modules to manage technical debt or perform security audits on third-party libraries.
| name | using-serena-symbols |
|---|---|
| description | Guidance for using Serena's LSP-powered symbol analysis. Use when exploring codebases, finding symbol definitions, tracing references, or when grep/text search would be imprecise. |
| allowed-tools | mcp__plugin_serena_serena__get_symbols_overview, mcp__plugin_serena_serena__find_symbol, mcp__plugin_serena_serena__find_referencing_symbols, mcp__plugin_serena_serena__read_file, mcp__plugin_serena_serena__search_for_pattern, mcp__plugin_serena_serena__list_dir |
Using Serena Symbol Analysis
Serena provides LSP-powered code intelligence for accurate symbol extraction, relationship discovery, and cross-file analysis.
When to Use Serena vs Text Search
| Use Serena | Use Grep/Text Search |
|---|---|
| Finding class/function definitions | Searching for string literals |
| Tracing method references | Finding patterns in comments |
| Understanding call hierarchies | Searching config files |
| Analyzing imports/dependencies | Finding TODO/FIXME markers |
| Cross-file architecture analysis | Simple keyword search |
Key advantage: Serena understands code structure. find_symbol("UserService") finds the actual class definition, not every mention of "UserService" in comments or strings.
Core Tools
1. get_symbols_overview
Get high-level view of symbols in a file. Start here when exploring a new file.
mcp__plugin_serena_serena__get_symbols_overview({
"relative_path": "src/services/auth.py",
"depth": 1 # 0=top-level only, 1=include methods
})
Returns: Classes, functions, variables with their kind and location.
2. find_symbol
Find symbols by name pattern. Supports flexible matching.
Name path patterns:
UserService- Find any symbol named "UserService"UserService/authenticate- Find method in class/UserService- Exact match (absolute path)Servicewithsubstring_matching: true- Matches "UserService", "AuthService", etc.
mcp__plugin_serena_serena__find_symbol({
"name_path_pattern": "UserService/authenticate",
"include_body": true, # Get source code
"depth": 0 # 0=just this symbol, 1=include children
})
Key parameters:
include_body(bool): Include source code (use judiciously for context)depth(int): How many levels of children to retrieverelative_path(str): Restrict search to file/directorysubstring_matching(bool): Partial name matching
3. find_referencing_symbols
Find all references to a symbol. Essential for understanding impact.
mcp__plugin_serena_serena__find_referencing_symbols({
"name_path": "UserService/authenticate",
"relative_path": "src/services/auth.py"
})
Returns: Code snippets showing each reference with context.
4. search_for_pattern
Regex search when you need flexibility (like grep, but smarter file filtering).
mcp__plugin_serena_serena__search_for_pattern({
"substring_pattern": "def.*async.*:",
"restrict_search_to_code_files": true,
"context_lines_before": 2,
"context_lines_after": 2
})
Standard Workflow
Exploring a New Codebase
Directory structure - Understand layout
mcp__plugin_serena_serena__list_dir({ "relative_path": ".", "recursive": false })Entry points - Find main files
mcp__plugin_serena_serena__get_symbols_overview({ "relative_path": "src/main.py", "depth": 1 })Trace key classes - Understand structure
mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "App", "include_body": false, "depth": 1 })
Understanding a Specific Class
Find the class with children
mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "AuthService", "depth": 1, "include_body": false })Read specific methods you need
mcp__plugin_serena_serena__find_symbol({ "name_path_pattern": "AuthService/validate_token", "include_body": true })Find who calls it
mcp__plugin_serena_serena__find_referencing_symbols({ "name_path": "AuthService/validate_token", "relative_path": "src/services/auth.py" })
Tracing Dependencies
Find all imports of a module
mcp__plugin_serena_serena__search_for_pattern({ "substring_pattern": "from.*auth.*import|import.*auth", "restrict_search_to_code_files": true })Find references to trace usage
mcp__plugin_serena_serena__find_referencing_symbols({ "name_path": "AuthService", "relative_path": "src/services/auth.py" })
Symbol Kinds Reference
LSP symbol kinds (for include_kinds/exclude_kinds filtering):
| Kind | Int | Description |
|---|---|---|
| File | 1 | |
| Module | 2 | |
| Namespace | 3 | |
| Package | 4 | |
| Class | 5 | |
| Method | 6 | |
| Property | 7 | |
| Field | 8 | |
| Constructor | 9 | |
| Enum | 10 | |
| Interface | 11 | |
| Function | 12 | |
| Variable | 13 | |
| Constant | 14 |
Example - find only classes:
mcp__plugin_serena_serena__find_symbol({
"name_path_pattern": "Service",
"substring_matching": true,
"include_kinds": [5] # Class only
})
Efficiency Tips
- Use
relative_pathto scope searches - much faster than searching entire codebase - Start with
include_body: false- get structure first, read code only when needed - Use
depth: 0initially - expand to children only when exploring specific classes - Combine with Forgetful - create memories for important architectural findings
Language Support
Serena works with any language that has an LSP server configured:
- Python (pyright/pylsp)
- TypeScript/JavaScript (tsserver)
- Rust (rust-analyzer)
- Go (gopls)
- Java (jdtls)
- And more...
The specific features available depend on the language server's capabilities.