Cross-repository code search for AI coding assistants

Use cross-repository code search with AI coding assistants: link SocratiCode indexes, verify source across services, and understand graph and deployment limits.

Repository boundaries hide system behaviour

A customer-facing change rarely respects a Git boundary. A frontend calls an API in another repository. That service publishes an event consumed elsewhere. A shared schema changes while the code that depends on it lives in several projects.

An AI assistant working inside one checkout can only reason from the material it can reach. Reading more files inside that repository does not reveal a sibling repository it was never given. This is a context boundary, not a model failure.

For a worked example of finding an implementation by behaviour, then narrowing the investigation with a known identifier, read semantic code search.

SocratiCode’s open-source cross-project pattern keeps one index per repository. It then links those indexes at query time.

frontend index ─┐
backend index  ─┼─ includeLinked search → combined ranked results
worker index   ─┘

Each repository remains independently indexable and inspectable. The link expands search coverage without pretending the repositories are one source tree.

First, index every repository separately and wait for codebase_status to report completion. They must use the same embedding provider, model, and EMBEDDING_DIMENSIONS so their results are comparable.

Then add the sibling project to the repository where the investigation starts:

{
  "linkedProjects": ["../backend"]
}

Save that as .socraticode.json at the project root, preserving any existing settings. Relative paths resolve from that root. Linking does not create or update the sibling’s index.

Run codebase_search with includeLinked: true. Every returned result carries a project label and file path. Check both before opening source.

Search crosses repositories; graphs do not

This distinction prevents a common overclaim. A linked search can return relevant files from several repositories in one result set. It does not create dependency or call-graph edges between those repositories.

If a result points into the backend, run graph or symbol tools using the backend’s projectPath. Trace that repository’s internal relationships there. The boundary between the frontend call and backend handler still needs to be verified through source, API contracts, configuration, or runtime evidence.

Cross-repository search widens discovery. It does not turn separate graphs into a verified distributed-system model.

What a useful investigation looks like

For an illustrative order-cancellation flow, start in the frontend with the backend already linked and both indexes current. The question is whether a completed state in the UI means the backend has finished the cancellation or only accepted the request.

Give the assistant this starting prompt:

Use SocratiCode to find where the order-cancellation screen decides
whether cancellation is pending or complete. Search this frontend
and its linked backend with codebase_search and includeLinked: true.

For every relevant result, show the project label and file path.
Read the frontend caller, backend handler, response schema and tests.
Set projectPath to each result's repository for graph or symbol analysis.
Check whether the UI state matches what the API actually guarantees.

Follow the returned evidence across the repositories:

  1. Search from the frontend for the user-visible behaviour with linked projects included.
  2. Confirm which results came from the frontend, backend, and any shared contract repository.
  3. Open the relevant source instead of relying on result summaries.
  4. Run symbol or flow analysis inside each result’s repository.
  5. Verify the hand-off between repositories against the actual API specification, event schema, configuration, and tests.

For example, if the contract returns acceptance immediately and completion arrives later through a status field or event, trace how the frontend handles that later signal. Use the actual schema and tests to decide what the UI should display. Check runtime behaviour where the source and contract leave a question open.

The useful result is a project-labelled caller/handler trace, the response guarantee, and the checks needed to validate that hand-off. This keeps the investigation tied to source and contract evidence.

Operating implications

Every linked repository needs its own completed, current index. The default watcher can keep changes current while its SocratiCode process is running, but a link does not create a cross-machine watcher and does not repair a stale sibling index.

Teams also need an access model. Linking a project should not grant a user access to source they were not already authorised to inspect. With the open-source route, that control belongs to the environment and services the team operates. SocratiCode Cloud is a private beta; managed access and deployment requirements must be confirmed during onboarding rather than assumed from this guide.

Adoption questions

For one repository shared by several people, read shared team context. For the separate data paths involved, read source-code boundaries.

Request beta access →

Prefer the open-source route? View source guide →