| name | search |
| description | Semantic codebase search — use for exploring code, finding implementations, and answering questions about any project. Searches using natural language queries, identifier names, or file paths. Returns ranked results using embedding-based similarity, BM25 keyword matching, symbol matching, import graph analysis, and git recency. Use this as the default exploration tool instead of grep when you don't know the exact text to search for. |
Semantic Codebase Search
Use search as your default exploration tool for understanding code, finding implementations, and answering questions about the codebase. Use grep when you already know the exact text or pattern you're looking for.
Indexing
The first query builds the index — this may take 10–60 seconds depending on project size. Subsequent queries are fast because the index is incrementally updated (only changed files are re-processed).
Query Types
The search tool supports three kinds of queries, automatically classified:
- Identifier queries — e.g.
AuthMiddleware, handleRequest, SearchEngine — finds definitions, usages, and related code for a specific symbol
- Natural language queries — e.g.
where is rate limiting handled, how does authentication work — semantic search across code and documentation
- Path queries — e.g.
src/auth/, packages/ai — finds code within a directory structure
Parameters
| Parameter | Required | Description |
|---|
query | Yes | Search query — natural language, identifier, or path |
searchDir | Yes | Directory to index and search — each unique value gets its own independent index |
restrictToDir | No | Filter results to files under this subdirectory within the already-built index (does not affect which files are indexed) |
limit | No | Maximum number of results to return (default: 20) |
rebuild | No | Force a clean index rebuild — use when files have changed significantly |
Ranking
Results are ranked using 6 signals fused via POEM (Pareto-Optimal Embedded Modeling):
- BM25 — keyword matching via FTS5 full-text search
- Cosine similarity — embedding-based semantic similarity (all-MiniLM-L6-v2)
- Path match — query terms appearing in the file path
- Symbol match — query terms matching function/class/type names
- Import graph proximity — files imported by or importing high-scoring files
- Git recency — recently modified files ranked higher
The weight given to each signal varies by query type. Identifier queries emphasize symbol match and BM25; natural language queries emphasize cosine similarity; path queries emphasize path match.
Results
Each result includes:
- File path and line range (start–end)
- Chunk kind (function, class, method, interface, heading_section, etc.) and name
- Metric scores for each of the 6 signals
- Content preview of the matching code or text
Tips
- Start broad, then narrow with
restrictToDir if you get too many results from different areas
- Use
limit to get more results when exploring a broad topic (e.g. limit: 50)
- Use
rebuild: true after major refactors, branch switches, or large file changes
- Identifier queries work best for finding where something is defined or used
- Natural language queries work best for understanding how a feature or concept is implemented
- Combine search with
grep for a powerful workflow: search to find the right files, then grep for exact patterns within them
