serena

Serena: Symbol-Level Code Understanding

Navigate and manipulate code at the symbol level using IDE-like semantic analysis powered by Language Server Protocol (LSP).

How You Can Access Serena

You may have Serena available in one or both of these ways:

Option 1: Direct MCP Tools (if configured by your orchestrator) Check your available tools for:

• find_symbol, find_referencing_symbols - Symbol lookup
• rename_symbol, replace_symbol_body - Refactoring
• insert_after_symbol, insert_before_symbol - Precise insertions
• onboarding, activate_project - Project understanding
• write_memory, read_memory - Save context
• And 25+ more LSP-powered tools

If you see these tools, use them directly - they provide full Serena capabilities!

Option 2: CLI Commands (always available via execute_command) You can run serena commands using:

execute_command("uvx --from git+https://github.com/oraios/serena serena <command>")

This skill focuses on CLI usage patterns. If you have direct MCP tools, prefer those for better integration.

Purpose

The serena skill provides access to Serena, a coding agent toolkit that transforms text-based LLMs into symbol-aware code agents. Unlike traditional text search (ripgrep) or structural search (ast-grep), Serena understands code semantics through LSP integration.

Key capabilities:

1. Symbol Discovery: Find classes, functions, variables, and types by name across 30+ languages
2. Reference Tracking: Discover all locations where a symbol is referenced or used
3. Precise Editing: Insert code at specific symbol locations with surgical precision

Serena operates at the symbol level rather than the text or syntax level, providing true IDE-like understanding of code structure, scope, and relationships.

When to Use This Skill

Use the serena skill when you need symbol-level code understanding:

Code Navigation:

• Finding where a class, function, or variable is defined
• Discovering all places where a symbol is used (call sites, imports, references)
• Understanding code dependencies and relationships
• Tracing execution flow through function calls

Code Understanding:

• Analyzing impact of changes to a function or class
• Understanding inheritance hierarchies and type relationships
• Identifying dead code (symbols never referenced)
• Mapping API usage patterns across a codebase

Code Refactoring:

• Renaming symbols while tracking all usage locations
• Adding methods or fields to specific classes
• Inserting error handling after specific function calls
• Modifying all call sites of a deprecated function

Choose serena over file-search (ripgrep/ast-grep) when:

• You need to understand symbol semantics (not just text patterns)
• You want to track references across files and modules
• You need precise insertion points based on code structure
• You're working with complex, multi-file codebases

Still use file-search when:

• Searching for text patterns, comments, or strings
• Finding todos, security issues, or documentation
• You need faster, simpler pattern matching
• Symbol-level precision isn't required

Language Support

Serena uses LSP servers for semantic analysis. Most common languages are supported out-of-the-box:

• Python (pyright, jedi)
• JavaScript/TypeScript (typescript-language-server)
• Rust (rust-analyzer)
• Go (gopls)
• Java (jdtls)
• C/C++ (clangd)
• C#, Ruby, PHP, Kotlin, Swift, Scala, and 15+ more

The LSP servers provide symbol information for the language you're working with.

Core Operations

1. Finding Symbols (find_symbol)

Locate where a symbol is defined in your codebase.

Note: All examples below use the short form serena <command>. The full command is:

uvx --from git+https://github.com/oraios/serena serena <command>

# Find a class definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'UserService' --type class")

# Find a function definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'authenticate' --type function")

# Find a variable definition
execute_command("uvx --from git+https://github.com/oraios/serena serena find_symbol --name 'API_KEY' --type variable")

Use cases:

• Locating the definition of a class before modifying it
• Finding where a function is implemented
• Understanding where constants are defined
• Tracing type definitions in typed languages

Output format:

File: src/services/user_service.py
Line: 42
Symbol: UserService (class)
Context: class UserService(BaseService):

2. Finding References (find_referencing_symbols)

Discover all locations where a symbol is used, imported, or referenced.

# Find all usages of a class
execute_command("serena find_referencing_symbols --name 'UserService'")

# Find all call sites of a function
execute_command("serena find_referencing_symbols --name 'authenticate'")

# Find all reads/writes of a variable
execute_command("serena find_referencing_symbols --name 'API_KEY'")

Use cases:

• Impact analysis before refactoring
• Finding all call sites of a function
• Tracking API usage across modules
• Identifying unused symbols (zero references)
• Understanding data flow and dependencies

Output format:

Found 12 references to 'authenticate':

1. src/api/routes.py:34
   authenticate(user_credentials)

2. src/middleware/auth.py:18
   from services import authenticate

3. tests/test_auth.py:56
   mock_authenticate = Mock(spec=authenticate)
...

3. Precise Code Insertion (insert_after_symbol)

Insert code at specific symbol locations with surgical precision.

# Add a method to a class
execute_command("""serena insert_after_symbol --name 'UserService' --type class --code '
    def get_user_by_email(self, email: str) -> Optional[User]:
        return self.db.query(User).filter_by(email=email).first()
'""")

# Insert error handling after a function call
execute_command("""serena insert_after_symbol --name 'database_query' --code '
    if result is None:
        raise DatabaseError("Query returned no results")
'""")

# Add a field to a dataclass
execute_command("""serena insert_after_symbol --name 'User' --type class --code '
    email_verified: bool = False
'""")

Use cases:

• Adding methods to existing classes
• Inserting validation or error handling
• Adding fields to data structures
• Injecting logging or monitoring code
• Implementing missing functionality

Safety features:

• Respects indentation and code formatting
• Maintains syntactic validity
• Positions code correctly within scope
• Preserves existing code structure

Workflow Patterns

Pattern 1: Safe Refactoring

When changing a function signature or behavior:

# Step 1: Find the function definition
serena find_symbol --name 'process_payment' --type function

# Step 2: Find all call sites
serena find_referencing_symbols --name 'process_payment'

# Step 3: Analyze impact (review output)
# [Review all usage locations to understand impact]

# Step 4: Make changes with confidence
# [Update function and all call sites based on findings]

Pattern 2: Adding Functionality

When extending a class with new methods:

# Step 1: Locate the class
serena find_symbol --name 'PaymentProcessor' --type class

# Step 2: Verify no conflicts
serena find_symbol --name 'process_refund' --type function

# Step 3: Insert new method
serena insert_after_symbol --name 'PaymentProcessor' --type class --code '
    def process_refund(self, payment_id: str, amount: float) -> bool:
        # Implementation here
        pass
'

Pattern 3: Understanding Dependencies

When analyzing code relationships:

# Step 1: Find class definition
serena find_symbol --name 'DatabaseManager' --type class

# Step 2: Find all usages
serena find_referencing_symbols --name 'DatabaseManager'

# Step 3: For each usage, find what symbols use that code
# [Repeat reference tracking to build dependency graph]

Pattern 4: Dead Code Detection

When identifying unused code:

# Step 1: Find symbol definition
serena find_symbol --name 'legacy_auth_handler'

# Step 2: Check references
serena find_referencing_symbols --name 'legacy_auth_handler'

# Step 3: If zero references (except definition), mark for removal
# [If output shows only the definition, symbol is unused]

Integration with file-search

Serena and file-search (ripgrep/ast-grep) are complementary tools. Use them together:

When to Combine Tools

Use ripgrep THEN serena:

# 1. Find potential matches with ripgrep (fast, broad)
rg "authenticate" --type py

# 2. Narrow to specific symbol with serena (precise)
serena find_symbol --name 'authenticate' --type function
serena find_referencing_symbols --name 'authenticate'

Use serena THEN ripgrep:

# 1. Find symbol definition with serena
serena find_symbol --name 'UserService'

# 2. Search for related patterns with ripgrep
rg "UserService\(" --type py  # Find direct instantiations
rg "class.*UserService" --type py  # Find subclasses

Complementary Strengths

Task	Best Tool	Why
Find string literals	ripgrep	Text-based, fast
Find TODOs/comments	ripgrep	Text-based
Find symbol definition	serena	Symbol-aware
Find all references	serena	Semantic understanding
Find code patterns	ast-grep	Syntax-aware
Insert at symbol	serena	Precise positioning
Search across languages	ripgrep	Language-agnostic
Understand scope	serena	LSP semantic info

Best Practices

1. Start with Symbol Discovery

Always locate the symbol definition first:

# GOOD: Find definition, then references
serena find_symbol --name 'MyClass'
serena find_referencing_symbols --name 'MyClass'

# AVOID: Searching for references without confirming definition exists

---

*Content truncated.*