Download the exact captured file
---
name: using-serena-symbols
description: Guidance for using Serena's LSP-powered symbol analysis. Use when you say "how do I find a symbol", "trace references for this method", "explore this file's structure", or when grep/text search would be imprecise. Do NOT use for memory guidance (use memory).
license: MIT
metadata:
routing:
role: conditional-adjunct
invoker: context-hub-setup
trigger: context-hub-setup lists using-serena-symbols as required once Serena is installed
user-facing: false
version: 1.0.0
---
# 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.
```python
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)
- `Service` with `substring_matching: true` - Matches "UserService", "AuthService", etc.
```python
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 retrieve
- `relative_path` (str): Restrict search to file/directory
- `substring_matching` (bool): Partial name matching
### 3. find_referencing_symbols
Find all references to a symbol. Essential for understanding impact.
```python
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).
```python
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,
}
)
```
## Process
### Exploring a New Codebase
1. **Directory structure** - Understand layout
```python
mcp__plugin_serena_serena__list_dir({"relative_path": ".", "recursive": false})
```
2. **Entry points** - Find main files
```python
mcp__plugin_serena_serena__get_symbols_overview({"relative_path": "src/main.py", "depth": 1})
```
3. **Trace key classes** - Understand structure
```python
mcp__plugin_serena_serena__find_symbol(
{"name_path_pattern": "App", "include_body": false, "depth": 1}
)
```
### Understanding a Specific Class
1. **Find the class** with children
```python
mcp__plugin_serena_serena__find_symbol(
{"name_path_pattern": "AuthService", "depth": 1, "include_body": false}
)
```
2. **Read specific methods** you need
```python
mcp__plugin_serena_serena__find_symbol(
{"name_path_pattern": "AuthService/validate_token", "include_body": true}
)
```
3. **Find who calls it**
```python
mcp__plugin_serena_serena__find_referencing_symbols(
{"name_path": "AuthService/validate_token", "relative_path": "src/services/auth.py"}
)
```
### Tracing Dependencies
1. **Find all imports of a module**
```python
mcp__plugin_serena_serena__search_for_pattern(
{"substring_pattern": "from.*auth.*import|import.*auth", "restrict_search_to_code_files": true}
)
```
2. **Find references to trace usage**
```python
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:
```python
mcp__plugin_serena_serena__find_symbol(
{
"name_path_pattern": "Service",
"substring_matching": true,
"include_kinds": [5], # Class only
}
)
```
## Efficiency Tips
1. **Use `relative_path`** to scope searches - much faster than searching entire codebase
2. **Start with `include_body: false`** - get structure first, read code only when needed
3. **Use `depth: 0`** initially - expand to children only when exploring specific classes
4. **Combine with Serena memory** - record important architectural findings with `mcp__serena__write_memory`
### Serena memory writes: check the checkout first
Serena writes to the checkout active at server start (`--project` root),
not your cwd. Call `mcp__serena__write_memory`, `edit_memory`,
`delete_memory`, or `rename_memory` only from that checkout. A linked worktree
(`git rev-parse --git-dir` differs from `--git-common-dir`) never qualifies.
In one, unsure, or without a shell, do not call them: edit `.serena/memories/`
files in your own checkout, or return the change to the parent session. Delete or
rename only when asked. New memory: `<topic>/<name>` plus a `memory-index.md` line.
See `universal.md` MUST NOT 11.
## Triggers
| 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 |
---
## When to Use
Use this skill when:
- Exploring class/function definitions with structural accuracy
- Tracing method call hierarchies across files
- Analyzing imports and dependencies
- Need code intelligence beyond text matching
Use Grep/text search instead when:
- Searching for string literals or comments
- Finding patterns in config files or YAML
- Looking for TODO/FIXME markers
- Simple keyword search across non-code files
---
## Anti-Patterns
| 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 |
---
## Verification
After symbol analysis:
- [ ] Correct symbol found (not a similarly named one)
- [ ] References traced to all call sites
- [ ] Scope was narrowed with relative_path where possible
- [ ] Results were token-efficient (include_body only when needed)
---
## 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.