semantic-code-hunter

name	semantic-code-hunter
description	Use when you need to find code by concept (not just text). Uses Serena MCP for semantic code search across the codebase with minimal token usage. Ideal for understanding architecture, finding authentication flows, or multi-file refactoring.

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