Skip to content

feat: add SOCRATICODE_PROJECT_ID for shared indexes across git worktrees#1

Merged
giancarloerra merged 3 commits intogiancarloerra:mainfrom
cstuncsik:feat/shared-project-id
Mar 15, 2026
Merged

feat: add SOCRATICODE_PROJECT_ID for shared indexes across git worktrees#1
giancarloerra merged 3 commits intogiancarloerra:mainfrom
cstuncsik:feat/shared-project-id

Conversation

@cstuncsik
Copy link
Contributor

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_ID environment variable that overrides the path-based project ID. All directories sharing the same value use the same Qdrant collections (codebase, codegraph, context).

Use case

"socraticode": {
  "command": "npx",
  "args": ["-y", "socraticode"],
  "env": {
    "SOCRATICODE_PROJECT_ID": "my-project"
  }
}

With this config, agents running in /repo/main, /repo/worktree-feat-a, and /repo/worktree-fix-b all share one index — no redundant embedding or storage.

Changes

  • src/config.ts: projectIdFromPath() checks SOCRATICODE_PROJECT_ID before 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

  • Zero behavioral change when the env var is unset (default path)
  • The explicit ID goes through the same collectionName() / graphCollectionName() / contextCollectionName() functions
  • Validation ensures the value is always Qdrant-friendly
  • File watcher and lock mechanisms work unchanged since they already use projectIdFromPath()

…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.
@cstuncsik cstuncsik force-pushed the feat/shared-project-id branch from ed10c06 to fadfd8a Compare March 15, 2026 09:59
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.
@giancarloerra giancarloerra self-assigned this Mar 15, 2026
@giancarloerra giancarloerra merged commit 60ac68f into giancarloerra:main Mar 15, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants