search_codebase

Hybrid code search over repowise's indexes: symbols, file paths, or the wiki, depending on the shape of the query. One tool instead of a fallback to Grep for identifiers.

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

Parameter	Type	Default	Description
`query`required	string	—	Identifier, path, or natural-language query.
`limit`	number	5	Max results to return.
`mode`	string	auto	auto (default) routes by query shape. concept forces wiki-semantic search. symbol / path force the structural search. hybrid runs symbol hits first, then concept pages.
`kind`	string	—	Filter results by kind: "implementation", "test", "config", "doc".
`symbol_kind`	string	—	Restrict symbol hits to a kind: "function", "class", "method", etc.
`page_type`	string	—	Concept mode only: filter by page kind: "file_page", "module_page", "symbol_spotlight".
`repo`	string	—	Repository alias. Pass "all" for a workspace-wide federated search, the one tool where "all" is fully supported.

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 to 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).

get_answer already runs a search internally before synthesizing. Reach for search_codebase when you want the list of candidates, not a synthesized answer, or when you know you're looking for a symbol or file by name.

search_codebase

Hybrid code search over repowise's indexes: symbols, file paths, or the wiki, depending on the shape of the query. One tool instead of a fallback to Grep for identifiers.

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

Parameter	Type	Default	Description
`query`required	string	—	Identifier, path, or natural-language query.
`limit`	number	5	Max results to return.
`mode`	string	auto	auto (default) routes by query shape. concept forces wiki-semantic search. symbol / path force the structural search. hybrid runs symbol hits first, then concept pages.
`kind`	string	—	Filter results by kind: "implementation", "test", "config", "doc".
`symbol_kind`	string	—	Restrict symbol hits to a kind: "function", "class", "method", etc.
`page_type`	string	—	Concept mode only: filter by page kind: "file_page", "module_page", "symbol_spotlight".
`repo`	string	—	Repository alias. Pass "all" for a workspace-wide federated search, the one tool where "all" is fully supported.

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 to 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).

When to call

Parameters

Modes

Returns

Example

Things worth knowing

On this page

search_codebase

When to call

Parameters

Modes

Returns

Example

Things worth knowing

On this page