semantic-code-hunter

Semantic Code Hunter (Powered by Serena MCP)

When to Use

• "Where do we handle X?" questions
• Finding authentication flows
• Locating validation logic
• Multi-file refactoring
• Understanding component relationships
• Finding all usages of a symbol
• Tracing dependencies

When NOT to Use

• Small projects (< 10 files) - use Grep instead
• Simple text searches - use Grep instead
• Single-file edits - use Read instead
• You already know the exact file

How It Works

Uses Serena MCP tools for semantic understanding:

• find_symbol - Find symbols by concept, not just name
• find_referencing_symbols - Trace code relationships
• find_referencing_code_snippets - Find where code is used
• get_symbols_overview - Understand file structure first
• Token-efficient (70% savings vs traditional search)

Serena Tools Available

find_symbol

Find symbols globally or locally with/containing a given name/substring.

Example: find_symbol("authenticate")
Finds: authenticateUser, isAuthenticated, AuthenticationService

find_referencing_symbols

Find symbols that reference another symbol.

Example: find_referencing_symbols("User", type="function")
Finds: All functions that use the User model

get_symbols_overview

Get high-level overview of symbols in a file.

Example: get_symbols_overview("src/services/auth.ts")
Returns: List of classes, functions, exports in file

search_for_pattern

Pattern search across project (when semantic search not sufficient).

Usage Pattern

Step 1: Start with Overview

If you know the file:
1. get_symbols_overview("path/to/file.ts")
2. Identify relevant symbols
3. Use find_symbol to get details

Step 2: Semantic Search

If you don't know the file:
1. find_symbol("concept")
2. Review results
3. Use find_referencing_symbols to trace usage

Step 3: Targeted Retrieval

Once you know what you need:
1. Use find_symbol to get specific code
2. Only loads relevant sections (not entire files)
3. Minimal token consumption

Examples

Example 1: Find Authentication Flow

Task: "Where do we handle user authentication?"

Process:
1. find_symbol("auth") - Find auth-related symbols
2. Identify: authenticateUser, validateToken, etc.
3. find_referencing_symbols("authenticateUser") - Where is it called?
4. Trace the flow: Login route → Auth service → JWT generation

Result: Complete authentication flow mapped without reading full files

Example 2: Multi-file Refactoring

Task: "Rename User model to Account"

Process:
1. find_symbol("User") - Find User model
2. find_referencing_symbols("User") - Find all usages
3. List all files that need updating
4. Use rename_symbol (Serena tool) for safe refactoring

Result: All references found and renamed consistently

Example 3: Understanding Component Relationships

Task: "How does ProjectCard component get data?"

Process:
1. find_symbol("ProjectCard")
2. find_referencing_symbols("ProjectCard") - Where is it used?
3. Trace backwards to data source
4. Understand the data flow

Result: Complete data flow from API → Page → Component

Best Practices

1. Start broad, narrow down

   • Use find_symbol with general terms first
   • Filter results by type (function, class, interface)
   • Then get specific symbol details

2. Use type filters

   • type="function" - Only functions
   • type="class" - Only classes
   • type="interface" - Only interfaces

3. Leverage symbol relationships

   • find_referencing_symbols shows dependencies
   • Helps understand impact of changes
   • Reveals architectural patterns

4. Combine with traditional tools

   • Serena for semantic understanding
   • Grep for simple text matches
   • Read for config files, documentation

Token Efficiency

Traditional approach (without Serena):

1. Read entire files → 10,000+ tokens
2. Multiple grep iterations → 5,000+ tokens
3. Manual analysis → High cognitive load

Serena approach:

1. find_symbol → 200 tokens
2. Targeted retrieval → 500 tokens
3. Total: ~700 tokens (93% savings)

Troubleshooting

If Serena returns too many results:

• Add type filter: type="function"
• Use more specific search term
• Check specific file with get_symbols_overview first

If Serena returns no results:

• Check spelling (case-sensitive)
• Try broader search term
• Fall back to Grep for text search
• Ensure Serena is indexed (run: serena project index)

If symbols missing:

• Re-index project: serena project index
• Check if file is in .gitignore
• Verify language server supports file type