feat: add SOCRATICODE_PROJECT_ID for shared indexes across git worktrees#1
Merged
giancarloerra merged 3 commits intogiancarloerra:mainfrom Mar 15, 2026
Merged
Conversation
…rectories When working with git worktrees (or any setup where the same codebase lives in multiple directories), each path currently gets its own Qdrant collection. This means the same codebase is indexed multiple times. This change adds a SOCRATICODE_PROJECT_ID environment variable that, when set, overrides the path-based project ID generation. All directories sharing the same SOCRATICODE_PROJECT_ID will use the same Qdrant collections (codebase, codegraph, context), eliminating redundant indexing. The value must match [a-zA-Z0-9_-]+ to remain Qdrant-friendly. An error is thrown at startup if the value contains invalid characters.
ed10c06 to
fadfd8a
Compare
Documents how to use SOCRATICODE_PROJECT_ID with per-project .mcp.json to share a single index across git worktrees of the same repository.
Claude Code resolves git worktree links back to the main repo path for config lookup, so MCP config only needs to be set once on the main checkout. All worktrees inherit it automatically. Separate clones are unaffected. Documents both the auto-detection path and the manual .mcp.json fallback for other MCP hosts.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When working with git worktrees (or any setup where the same codebase lives in multiple directories), each path currently generates a unique Qdrant collection. This means the same codebase gets indexed redundantly for every worktree.
This PR adds a
SOCRATICODE_PROJECT_IDenvironment variable that overrides the path-based project ID. All directories sharing the same value use the same Qdrant collections (codebase, codegraph, context).Use case
With this config, agents running in
/repo/main,/repo/worktree-feat-a, and/repo/worktree-fix-ball share one index — no redundant embedding or storage.Changes
src/config.ts:projectIdFromPath()checksSOCRATICODE_PROJECT_IDbefore hashing the path. Validates the value matches[a-zA-Z0-9_-]+.tests/unit/config.test.ts: 6 new tests covering the env var override, validation, whitespace trimming, and fallback behavior.README.md: Documents the new env var in the Indexing Behavior table.Why this is safe
collectionName()/graphCollectionName()/contextCollectionName()functionsprojectIdFromPath()