From copilot-cli-toolkit
Guides using Serena's LSP tools for codebase exploration, symbol definitions, reference tracing, call hierarchies, and precise analysis beyond grep/text search.
npx claudepluginhub rjmurillo/ai-agentsThis skill uses the workspace's default tool permissions.
Serena provides LSP-powered code intelligence for accurate symbol extraction, relationship discovery, and cross-file analysis.
Guides using Serena's LSP tools for codebase exploration, symbol definitions, reference tracing, call hierarchies, and precise analysis beyond grep/text search.
Guides use of Serena's LSP tools for symbol overviews, finding definitions, tracing references, and codebase exploration where grep is imprecise.
Provides IDE-like semantic symbol operations for large codebases: find/rename/refactor symbols, cross-file reference tracking, project memory, multi-language navigation.
Share bugs, ideas, or general feedback.
Serena provides LSP-powered code intelligence for accurate symbol extraction, relationship discovery, and cross-file analysis.
| 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.
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.
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)Service with substring_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 matchingFind 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.
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
})
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
})
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"
})
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"
})
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
})
relative_path to scope searches - much faster than searching entire codebaseinclude_body: false - get structure first, read code only when neededdepth: 0 initially - expand to children only when exploring specific classes| Trigger Phrase | Operation |
|---|---|
how do I find a symbol | find_symbol with name_path_pattern |
how do I explore a file's structure | get_symbols_overview with depth |
how do I trace references | find_referencing_symbols |
how do I search code patterns | search_for_pattern with regex |
what methods does this class have | find_symbol with depth=1 |
Use this skill when:
Use Grep/text search instead when:
Use serena-code-architecture instead when:
| Avoid | Why | Instead |
|---|---|---|
| Searching entire codebase without relative_path | Slow, noisy results | Scope with relative_path parameter |
| Starting with include_body=true | Wastes tokens on code you may not need | Start with include_body=false, read selectively |
| Using depth > 1 on large modules | Returns excessive nested symbols | Use depth=0 or depth=1, expand as needed |
| Using text grep for symbol definitions | Matches comments, strings, false positives | Use find_symbol for structural accuracy |
| Skipping get_symbols_overview | Jumping to find_symbol without context | Start with overview to understand file structure |
After symbol analysis:
Serena works with any language that has an LSP server configured:
The specific features available depend on the language server's capabilities.