[Feature]: cross-project search and dependency resolution for linked repositories

[giancarloerra]

Problem or motivation

Developers often work across multiple related repositories simultaneously — an API and its SDK, a service and its shared types library, a frontend and its backend. Today, each project gets its own isolated Qdrant collections. Search and code graph are scoped to a single project at a time.

This means when you're working in backend-api/ and it imports types from shared-types/ (a separate repo cloned alongside it), the code graph can't resolve those cross-repo imports, and codebase_search can't find relevant context from the related project. You have to mentally context-switch between projects or rely on the AI agent to guess.

For the single developer working across 2-3 related local repos, unified search and cross-project dependency resolution would significantly improve AI context quality without requiring a monorepo structure.

Proposed solution

A lightweight linked projects model that bridges existing per-project collections without merging them.

1. Project linking configuration

A .socraticode.json file at the project root (or SOCRATICODE_LINKED_PROJECTS env var) declares related project paths:

{
  "linkedProjects": [
    "../shared-types",
    "../frontend"
  ]
}

Paths are resolved relative to the project root. Each linked project must be independently indexed (has its own collections).

2. Cross-project search

codebase_search gains an optional parameter (e.g. includeLinked: true or scope: "linked") that queries across the current project's collection and all linked projects' collections in parallel:

1. Query each collection independently (same hybrid dense + BM25 search)
2. Merge results with RRF fusion across collections
3. Deduplicate by file path, annotating results with project source
4. Return ranked results with a project field so the AI knows which repo each result came from

Default behavior remains single-project (backward compatible).

3. Cross-project graph resolution

When building the code graph, attempt to resolve imports that point to a linked project:

• import { Foo } from '@company/shared-types' → check if any linked project contains that module
• Cross-project edges are marked as external in the graph so they're distinguishable from internal dependencies
• codebase_graph_query can optionally traverse into linked projects

Phased approach

Phase 1 — Cross-project search (highest value, lowest complexity)

• .socraticode.json config parsing
• Multi-collection query dispatch in codebase_search
• Client-side RRF fusion across result sets

Phase 2 — Cross-project graph links

• Import resolution across linked project collections
• External edge type in the graph model
• codebase_graph_query traversal across project boundaries

Phase 3 — Quality of life

• codebase_status shows linked projects and their index status
• Auto-discovery: detect related projects from package.json workspaces, go.work, etc.
• Linked project watcher coordination

Alternatives considered

• Indexing everything under a parent directory — works but creates one massive index mixing unrelated code. Loses project isolation and makes cleanup harder.
• SOCRATICODE_PROJECT_ID to force shared collections — merges projects into one index but loses the ability to manage/remove them independently. Also conflates file paths from different repos.
• Monorepo restructuring — not always practical or desirable, especially with external dependencies or team boundaries.

Area

Search, Code graph, MCP tools / API

Additional context

Inspired by community feedback about cross-repo dependency mapping in enterprise setups. The proposed approach stays true to SocratiCode's design — a dev tool for individual developers — while enabling multi-repo workflows without requiring enterprise infrastructure.

This builds naturally on the existing architecture: each project keeps its own isolated collections, and the linking layer is purely a query-time concern (Phase 1) with optional build-time graph enrichment (Phase 2).

Related: #19 (branch-aware index hierarchy) addresses a different axis of the same "one project ID = one index" limitation.

Checklist

• I have searched existing issues and this hasn't been requested before