Search Codebase
synapse_search_codebaseSearch codebases using semantic, symbol, or regex modes to find relevant code and get compressed responses focused on the intended repository.
Instructions
Searches the repository codebase using different modes. Pass the exact repo_id with every action to keep results focused on the intended repository; if repo_id is unknown, call synapse_manage_repos with action 'list'. High-level actions include:
'semantic': cosine similarity search over in-memory embeddings; best for conceptual or descriptive queries.
'symbol': fast exact/fuzzy symbol index lookup; best when looking for a named function, module, or class.
'regex': line-matching grep over indexed source; best for exact string or pattern matching. Without repo_id, every action returns at most 5 high-confidence matches across indexed repositories and reports the policy in meta.unscoped_retrieval.
REPLACES: grep_search, find, rg, list_dir for code search. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Search codebase using semantic embeddings, symbol index, or regex grep. Pass the exact repo_id to keep results focused on the intended repository. For the freshest just-edited file, use actions 'symbol' or 'regex' (analogous to current symbol, regex, and graph context workflows).
Usage (long): Run a natural language semantic search, exact/fuzzy symbol lookup, or line-matching regex grep over indexed files. Pass the exact repo_id with every action to keep results focused on the intended repository. If repo_id is unknown, call synapse_manage_repos with action 'list' and copy it verbatim. Without repo_id, semantic requires score >= 0.75, fuzzy symbols require score >= 0.90, regex keeps exact textual matches, and every action is capped at 5 results. The response reports this in meta.unscoped_retrieval. Compression is on by default — pass compress_payload: false to opt out for debugging. Actions 'symbol' and 'regex' work immediately after quick_pass — they do not require embeddings. Action 'semantic' requires embeddings — avoid when repo_status.embeddings_partial is true.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter results by entity kind (e.g., function, module). | |
| path | No | Filter results by partial file path. | |
| fuzzy | No | Enable fuzzy matching (default true, used in symbol). | |
| limit | No | Maximum number of results to return. | |
| query | No | Search query (natural language for semantic, regex for regex, symbol name for symbol). | |
| action | Yes | Search mode to execute. | |
| symbol | No | Symbol name to look up (alternative to query for action 'symbol'). | |
| repo_id | No | Repository identifier. Pass the exact repo_id to keep results focused on the intended repository and avoid matches from unrelated registered repositories. If unknown, call synapse_manage_repos with action 'list' and copy the repo_id verbatim. When omitted, semantic uses score >= 0.75, fuzzy symbols use score >= 0.90, and every action is capped at 5 results. | |
| language | No | Filter results by programming language. | |
| min_score | No | Minimum similarity score (used in semantic, default 0.6). | |
| max_tokens | No | Approximate final response budget in tokens (500-32000, default 4000). | |
| exclude_tests | No | Exclude test files from search results (default true, used in semantic). | |
| match_per_line | No | Return per-line matches with file path, line number, and line content (like grep -n). Use this when hunting for specific function definitions or call sites — results include repo_id, file, line_number, line_content. | |
| case_insensitive | No | Ignore case in regex search (default false, used in regex). | |
| compress_payload | No | Set false to disable lossless response-key compression. | |
| wait_for_ready_ms | No | Optional timeout in ms to wait for the indexer to finish warming up and enter an idle state before executing. Use to ensure stable results. |