search_codebase

A single tool that, depending on the shape of the query, searches the indexed symbols, file paths, or the wiki. An identifier routes to symbol hits, a path-shaped query to file hits, and prose to wiki-semantic search — so the agent doesn't need to pick a strategy up front.

When to call

• Locating a function/class/method by name — symbol hits pipe directly into get_symbol.
• Resolving a path-shaped query — file hits pipe into get_context.
• After get_answer when confidence is medium or low — explore the alternatives, or discover pages by topic before drilling in.

Parameters

Modes

• auto (default) routes by query shape:
  • an identifier (GitIndexer, index_repo) → searches indexed symbols;
  • a path (core/ingestion/indexer.py) → searches file pages;
  • prose ("how do we handle retries?") → wiki-semantic search;
  • mixed prose + identifier → hybrid (symbol hits first, then concept pages).
• concept forces the original wiki-semantic behavior.
• symbol / path force the structural search.

Returns

• Symbol hits: {type: "symbol", symbol_id, name, kind, file, start_line, end_line, signature, next: "get_symbol"}. Ranked by exact-name/qualified-name match, query-token coverage, then graph centrality (PageRank / betweenness / entry-point); non-test results rank before test unless kind="test".
• File hits: {type: "file", page_id, file, title, next: "get_context"}.
• Concept hits: ranked wiki pages with page_id, title, page_type, snippet, target_path, relevance_score (raw, absolute), confidence_score (normalized to the top result), and search_method ("embedding" vs "bm25" fallback).

Tombstoned and exclude_patterns-excluded results are filtered out. In workspace mode, structural and concept searches both federate across repos and merge.

Example

search_codebase(query="GitIndexer index_repo")           # -> symbol hits
search_codebase(query="core/ingestion/indexer.py")       # -> file hits
search_codebase(query="rate limit OR throttle OR retry") # -> wiki pages
search_codebase(query="login", mode="symbol", symbol_kind="method")
search_codebase(query="caching strategies", repo="all")

Things worth knowing

• Vector + FTS fallback — concept-mode semantic search runs first with an 8-second timeout. If the vector store is unavailable or slow, full-text search takes over transparently.
• Fetch-and-filter — concept mode fetches 3× the requested limit, then filters by page_type and a minimum relevance threshold, keeping results rank-stable when filters are applied.
• Freshness boost — concept results are re-ranked by git activity. Files with commits in the last 30 days get a 1.0× boost, 60–90 days get 0.5×, inactive get 0.0×.
• Workspace-wide (repo="all") — uses Reciprocal Rank Fusion (k=60) to merge per-repo results; confidence scores are renormalized within the merged set. This is the one tool where repo="all" is fully supported (get_context and get_overview also accept it; get_symbol, get_dependency_path, and get_execution_flows do not).