Code Search

The eight tools

Argument reference

search_codebase — required: query, repo_ids. Optional: top_k (default 10), file_filter (substring match on file path), min_score (0–1, default 0.0 — raise to ~0.7 to drop weak matches).

multi_repo_search — required: query. Optional: repo_ids (omit to search every indexed repo), top_k, file_filter, min_score.

find_similar_code — required: code (the snippet to find analogues of). Optional: repo_ids, top_k, file_filter, min_score.

list_indexed_files — required: repo_id. Optional: file_filter.

get_file_chunks — required: repo_id, filename (relative path as returned by search_codebase).

grep — required: path (absolute), pattern. Optional: file_pattern (glob filter when path is a folder, default *), recursive (default true), ignore_case (default false), fixed (literal substring, default false), context (lines before/after each match, default 0), max_matches (default 1000).

glob — required: folder_path (absolute), Optional: pattern (default **/*), recursive (default true), include_dirs (default false), include_hidden (default true), max_results (default 1000).

read_file_by_lines — required: file_path (absolute — the paths the other tools return). Optional: start_line (default 1), end_line (default 100).

Which agents get them

grep, glob and read_file_by_lines are default tools for every agent. The five index tools — search_codebase, multi_repo_search, find_similar_code, list_indexed_files and get_file_chunks — are defaults for Code agents, and are removed from every agent while Code repository indexing is off.

Where they can read

grep, glob and read_file_by_lines are scoped to indexed repositories — every linked repository — plus the vault and the folders in Settings → General → Allowed directories, the same list the built-in Filesystem server starts from. Given an absolute path outside those, the call is refused, whether or not the file exists: Access denied: '…' is outside the folders agents may read. Agents may read only inside linked repositories, the vault, and the folders listed in Settings → Allowed Directories. A .. in a path or pattern, or a symbolic link out of a repository, reaches nothing outside them. This is enforced where the tool runs, not by the agent's prompt.

Setting up code search

1. Enable code repository indexing

Open Settings → General and toggle Code repository indexing on. The first time you enable it, SynapseOrch walks you through the PostgreSQL + pgvector setup (see PostgreSQL + pgvector setup below).

2. Add a repository

First pick an Embedding model in Settings → Models. There is no default, and indexing fails until one is set. See Code Repositories for the models SynapseOrch knows.

Then go to Settings → Repos and click Add repo. The form asks for:

The default file types are *.py, *.ts, *.tsx, *.js, *.jsx, *.rs, *.go, *.java, *.md, *.html, *.vue, *.svelte, *.css, *.scss, *.cpp and *.c. Dotfiles, node_modules, __pycache__, venv, .git and *.pyc are excluded by default, and about fifty build, dependency, cache and editor patterns — dist, build, target, vendor, coverage, *.lock, *.log, *.min.js and so on — are always excluded; Always excluded automatically in the form lists them.

3. Index the repository

Click Save repository. If the path exists and indexing is on, indexing starts straight away — there is no separate Index button. SynapseOrch splits each file into overlapping chunks of about 1,000 characters, following the language's structure where it can, embeds each chunk, and writes the vectors to PostgreSQL.

The card shows the status — indexing, indexed, stopping, stopped or error — and a running count of chunks indexed. Stop indexing cancels a run in progress. Large repos (10k+ files) take a few minutes.

4. Assign repos to agents

Open the agent in Agents, set Agent Type to Code, and click the repos this agent should search under Linked Repositories. Only Code agents have linked repositories, and their system prompt tells them which repos they have and nudges them to use search_codebase early.

Advanced: the agent JSON

{ "type": "code", "repos": ["repo_1726412345678", "repo_1726412399012"] }

Repo ids have the form repo_<digits>; an id in any other form is skipped by the search tools.

Example agent prompts

Find the function that handles MCP server registration

Where is the vault_write tool implemented?

Show me all places where the anthropic client is initialised

Find tests for the orchestration engine

For exact-string lookups (error messages, env var names), nudge the agent toward grep:

Use grep to find every place that references AWS_SECRET_KEY in the backend repo

Re-indexing

After significant code changes, click Re-index on the repo card. Re-indexing is incremental — only changed files are processed — unless the embedding model's vector size has changed, which forces a full rebuild.

PostgreSQL + pgvector setup

Toggling Code repository indexing in Settings → General kicks off a guided setup that adapts to what SynapseOrch finds on your machine:

If you prefer to set it up manually:

CREATE DATABASE synapse;
\c synapse
CREATE EXTENSION vector;

Then point SynapseOrch at it via Settings → General → Code repository indexing → connection form.