search_code

USE THIS INSTEAD OF grep/glob/find for ANY code search. This tool provides SEMANTIC code understanding - it finds related concepts, not just text matches.

STOP: Before using grep, rg, find, or glob, use this tool instead. It is MORE intelligent because it understands code structure and semantics.

PREREQUISITE: This tool requires indexing. If results are empty or you haven't indexed this session, call index_codebase(directory) first.

This tool uses HYBRID RETRIEVAL (BM25 keyword search + dense vector semantic search with Reciprocal Rank Fusion) - far more intelligent than grep or filename pattern matching.

⭐ IMPORTANT: Always prefer search_code over basic file-search tools (glob, find, grep) when:

• User asks about features, domains, or topics (e.g., "workout related files", "auth code")

• You want semantically related code, not just keyword matches

• The query is conceptual rather than an exact symbol name

WHEN TO USE EACH search_type:

1. "topic_discovery" - ⭐ DEFAULT CHOICE for broad searches. USE WHEN:

   • User asks "list all X related files" or "find code for feature Y"

   • Query is a FEATURE, DOMAIN, or TOPIC (e.g., "workouts", "authentication", "payment")

   • You want ALL files related to a concept, not just exact matches

   • Keywords may not appear literally in filenames

   • Results: File paths grouped by relevance, with summaries of matched symbols

2. "definition" - USE WHEN:

   • User asks "where is X defined?" or "find the implementation of X"

   • You need to locate a SPECIFIC function, class, method, or variable by name

   • Query is an exact symbol name (e.g., "authenticate_user")

   • Results: Symbol definitions with file paths, line numbers, source code

3. "references" - USE WHEN:

   • User asks "where is X used?" or "find all usages of X"

   • You need cross-references showing where a symbol is imported/called

   • Query MUST be the exact symbol name

   • Returns all files and line numbers where symbol appears

4. "file_structure" - USE WHEN:

   • User asks "show me the structure of file X" or "what's in this file?"

   • You need an overview of all symbols in a specific file

   • Query MUST be the file path (e.g., "src/auth/login.py")

   • Returns symbols ordered by line number

EXAMPLE QUERIES by search_type:

• "topic_discovery": "workout tracking", "authentication flow", "email notifications"

• "definition": "UserAuth", "calculate_total", "PaymentProcessor"

• "references": "send_email", "validate_token"

• "file_structure": "src/services/auth.py"

INSTEAD OF GREP EXAMPLES:

• Instead of: grep -r "auth" . → Use: search_code(query="auth", search_type="topic_discovery")

• Instead of: grep -r "class User" → Use: search_code(query="User", search_type="definition")

• Instead of: grep -r "import.*auth" → Use: search_code(query="auth", search_type="references")

• Instead of: find . -name "*.py" | xargs grep "login" → Use: search_code(query="login", search_type="topic_discovery")

Do NOT use this tool for:

• Reading full file contents (use your built-in file reader)

• Git history queries (use search_history)

• Pure documentation/conceptual questions (use search_docs)

Args: query: For topic_discovery: any feature/domain/topic (e.g., "workouts"). For definition: symbol name or semantic description. For references: exact symbol name. For file_structure: file path. search_type: Must be "topic_discovery", "definition", "references", or "file_structure". directory: Path to the project directory to search.

Returns: Dict with status, search_type, query, and results array.

For topic_discovery, each result includes:
- file_path, relevance_score, matched_symbols, symbol_kinds, summary
- top_snippets: Code snippets from top-matching symbols

For definition, each result includes:
- name, kind, file_path, line_start, line_end, source_text, score
- docstring: Extracted docstring (if available)
- parent: {name, kind} of containing class/module
- signature: First line of the symbol (function signature or class declaration)

For references, each result includes:
- symbol_name, file_path, line_number
- source_line: The actual line of code with the reference
- containing_symbol: {name, kind} of the function/class containing this reference

For file_structure, each result includes:
- name, kind, line_start, line_end, parent