search

Semantic Codebase Search

search is one optional tool in your exploration toolkit — best for open-ended exploration of a large code or text corpus (especially code repos) when you don't know the exact keywords. 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):

1. BM25 — keyword matching via FTS5 full-text search
2. Cosine similarity — embedding-based semantic similarity (all-MiniLM-L6-v2)
3. Path match — query terms appearing in the file path
4. Symbol match — query terms matching function/class/type names
5. Import graph proximity — files imported by or importing high-scoring files
6. 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