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.
Keep indexes separate, link them for 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
Suppose a frontend receives a response field whose meaning has changed:
- Search from the frontend for the user-visible behaviour with linked projects included.
- Confirm which results came from the frontend, backend, and any shared contract repository.
- Open the relevant source instead of relying on result summaries.
- Run symbol or flow analysis inside each result’s repository.
- Verify the hand-off between repositories against the actual API specification, event schema, configuration, and tests.
This sequence gives the assistant a wider starting point while keeping claims tied to 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
- Which repositories make up the user journey or service boundary being investigated?
- Who keeps each index current, and how is freshness checked?
- Are embedding profiles identical across the linked projects?
- Can every intended user access every linked repository?
- Which cross-repository hand-offs need contract or runtime verification beyond search?
For one repository shared by several people, read shared team context. For the separate data paths involved, read source-code boundaries.