LiteLLM Proxy Server (https://docs.litellm.ai/docs/simple_proxy) exposes an
OpenAI-compatible /v1/embeddings endpoint and fans out to 100+ underlying
providers (OpenAI, Anthropic, Cohere, Voyage, HuggingFace, Bedrock, Vertex AI,
Ollama, ...). Mirroring the lmstudio strategy (PR #42 + commit bb141a0) but
with three meaningful differences that justify a dedicated provider rather
than a flag on provider-openai:
- Authentication is mandatory. LiteLLM gates /v1/models with the master key
or a virtual key, unlike LM Studio (no auth by default) and OpenAI (cloud
key). LITELLM_API_KEY is checked at config-load time; the provider also
duck-types 401/403 in ensureReady/healthCheck via err.status to surface a
distinct "auth rejected" message vs. "proxy unreachable".
- Model aliases come from the proxy's config.yaml, so EMBEDDING_MODEL and
EMBEDDING_DIMENSIONS have no sensible defaults. Fail-fast in
loadEmbeddingConfig with provider-specific error messages pointing at
litellm_params.model in the proxy config and at the underlying alias's
output dim.
- Whether dimensions can be forwarded depends on the underlying provider:
Matryoshka-aware models (text-embedding-3-*, voyage-3) accept it,
non-Matryoshka backends (BGE, nomic, Cohere v3) reject. Made opt-in via
LITELLM_SEND_DIMENSIONS=true rather than hardcoded like provider-openai
does for text-embedding-3-*, since LiteLLM aliases are user-defined.
Encoding-format=float fix from bb141a0 ports verbatim — the OpenAI SDK 6.x
base64-decode path corrupts any backend that returns plain JSON float arrays
(many LiteLLM aliases do, including Ollama-routed and tei-wrapped ones).
Files:
- src/services/provider-litellm.ts: new LiteLLMEmbeddingProvider with the
same OpenAI-SDK + custom baseURL pattern. Default baseURL
http://localhost:4000/v1 (LiteLLM's default port, /v1 prefix required).
Batch size 256 — between OpenAI's 512 and LM Studio's 64, since the
practical ceiling depends on whichever provider the alias resolves to.
ensureReady distinguishes proxy-unreachable / auth-rejected /
alias-not-registered. Lists up to 10 currently-registered models in the
alias-missing error so the operator can sanity-check their config.yaml
without leaving the log.
- src/services/embedding-config.ts: extends EmbeddingProvider union with
"litellm", adds litellmUrl to EmbeddingConfig, fail-fast validation for
LITELLM_API_KEY + EMBEDDING_MODEL + EMBEDDING_DIMENSIONS (key first so a
virtual-key user fixes the easy problem before touching the proxy
config), updates Invalid EMBEDDING_PROVIDER message and hasApiKey log
expression.
- src/services/embedding-provider.ts: factory case for litellm with dynamic
import to avoid loading the OpenAI SDK at startup for non-litellm users.
- README.md: dedicated LiteLLM section, MCP host config example, env-var
table entries for EMBEDDING_PROVIDER / EMBEDDING_MODEL /
EMBEDDING_DIMENSIONS / EMBEDDING_CONTEXT_LENGTH (clarifying which require
manual values for litellm), new LiteLLM Configuration table.
- tests/unit/embedding-config.test.ts: 9 new cases (model + dim + key
required, error-ordering, URL default + override, dimensions parsing,
EMBEDDING_CONTEXT_LENGTH override for unknown aliases, auto-detection
when alias matches a known model name) plus updated "full external
config" expected object and updated invalid-provider error message.
- tests/unit/embedding-provider.test.ts: factory test for litellm, plus 4
cases against a deliberately-closed port (config rejects construction
without API_KEY, ensureReady unreachable error format, healthCheck
short-circuits on missing key without a network call, healthCheck
reaches "Not reachable" path without throwing).
Backward compatible. The litellm provider is opt-in via
EMBEDDING_PROVIDER=litellm. Existing ollama, openai, google, and lmstudio
paths are untouched.
Verified: 64/64 unit tests pass on the touched suites; biome lint clean;
tsc --noEmit clean.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds an optional `projectId` field to `.socraticode.json` so teams can
commit a stable project identifier to the repo. Without this field the
project ID is derived from the SHA-256 of the absolute checkout path,
which means the same project resolves to a different Qdrant collection
on every machine, OS user, filesystem layout, or worktree. With it,
every checkout addresses the same `codebase_*`, `codegraph_*`, and
`context_*` collections regardless of where the working tree lives on
disk.
This is the path-independent, multi-project complement to the existing
`SOCRATICODE_PROJECT_ID` env var. The env var is process-scoped and
global to all projects in a host, so it does not scale to a developer
who works on several projects on one laptop. The file is per-project
and shared across teammates via git.
Resolution precedence (highest first):
1. `SOCRATICODE_PROJECT_ID` env var (per-machine override)
2. `projectId` in .socraticode.json (committed, team-wide)
3. SHA-256 prefix of the absolute path (existing default)
Both override paths trim whitespace, validate against `[a-zA-Z0-9_-]+`,
and throw on invalid characters so a misconfigured value cannot
silently route a project to the wrong (or empty) collection. Malformed
JSON, missing fields, wrong types, and empty/whitespace-only values
fall through to the next precedence level so the MCP server stays
resilient against hand-edited config files. Branch-aware mode is
suppressed for either explicit override since explicit identifiers
are stable by intent.
Also fixes a pre-existing bug in `resolveLinkedCollections`: linked
projects were resolved via `coreProjectId(linkedPath)` (path hash
only), so a linked project that pinned its own `projectId` in
`.socraticode.json` would silently miss its actual data during
cross-project search. Linked-project resolution now goes through a
new `effectiveBaseProjectId` helper that honors the committed value,
preserving symmetry: a project addresses the same Qdrant collection
whether it is the current root or a linked dependency. Dedup is
tightened to use the same effective base ID, so two paths pinning the
same shared identifier collapse to a single result.
The env var deliberately does not leak into linked-project collection
names. It is process-scoped and applying it as a single value to every
linked path would collapse them onto the env-var collection, silently
losing per-project isolation.
Tests: 16 new cases in tests/unit/config.test.ts, written TDD-style
(RED to GREEN). Coverage:
- `projectIdFromPath` (13): file resolution, ignores path
differences when file projectId is set, whitespace trimming,
throws on invalid characters, falls back to hash on
empty/whitespace/wrong-type/null/missing-file/malformed-JSON,
env-var precedence over file, branch-suffix suppression, and
coexistence with `linkedProjects` in the same file.
- `resolveLinkedCollections` (3): linked project's committed
projectId honored, dedup on shared committed projectId, env var
does not leak into linked-project collection names.
The new branch-aware-suppression test explicitly disables git
`commit.gpgsign` and `tag.gpgsign` in its throwaway-repo fixture so
the test is robust against the developer's global git config.
Backwards compatible: zero behaviour change for users who do not adopt
the new field. The `SocratiCodeConfig` interface gains an optional
field; existing `linkedProjects` parsing is functionally identical
(routed through the new shared `loadSocratiCodeConfig` helper).
Composes cleanly with the recently-added `QDRANT_COLLECTION_PREFIX`:
prefix + projectId combine into `<prefix>codebase_<projectId>` as
expected.
README and DEVELOPER documentation updated: new "Team-Shared Index
(committed `projectId`)" section in README between Git Worktrees and
Cross-Project Search, and the env-var table notes the new precedence.
DEVELOPER's "Project ID & Collection Naming" section now documents
the three-level precedence and explains why both override paths
suppress the branch-aware suffix.
Co-authored-by: airmonitor <tomasz.szuster@gmail.com>
Resolves#49. Reported by @awbait.
When sharing a single Qdrant server across multiple applications
(SocratiCode + Open-WebUI + custom RAG, etc.) or across multiple
SocratiCode instances (per-project, per-environment, per-user), the
fixed `codebase_<id>` / `codegraph_<id>` / `context_<id>` /
`<id>_symgraph_*` / `socraticode_metadata` collection names risk
colliding with other apps and prevent isolation between SocratiCode
instances.
This patch adds an optional QDRANT_COLLECTION_PREFIX env var that, when
set, is prepended verbatim to every Qdrant collection name SocratiCode
creates, queries, lists, or deletes. Default empty string preserves the
existing collection names exactly: fully backwards compatible.
Touchpoints (mechanical, no logic changes):
- src/constants.ts: new QDRANT_COLLECTION_PREFIX export with eager
validation. Qdrant accepts only [a-zA-Z0-9_-] in collection names; an
invalid prefix throws at module load with a message naming the
offending value, before any Qdrant call is attempted.
- src/config.ts: all six collection-name generators
(collectionName, graphCollectionName, contextCollectionName,
symgraphMetaCollectionName, symgraphFileCollectionName,
symgraphIndexCollectionName) prepend the prefix. Generator semantics
are otherwise unchanged.
- src/services/qdrant.ts: METADATA_COLLECTION (the global
socraticode_metadata collection used for cross-project state) also
honours the prefix, so two SocratiCode instances on one Qdrant keep
their metadata isolated as well as their per-project collections.
The two startsWith() filters in listCodebaseCollections — used by
codebase_list_projects to discover this instance's collections —
build the match prefix from QDRANT_COLLECTION_PREFIX so a prefixed
instance only sees its own collections, not those of co-tenants.
- src/tools/manage-tools.ts: codebase_list_projects similarly uses the
prefix in its filters. The projectId extraction (formerly
c.replace("codebase_", "")) now slices the full
${prefix}codebase_ token so the recovered id is correct under any
prefix; the codegraph cross-reference uses the same prefixed name.
Tests: 20 new test cases in tests/unit/qdrant-collection-prefix.test.ts
covering:
- Default empty prefix preserves the legacy collection-name forms for
all six generators (regression guard against backward-compat break).
- Empty-string env var is treated identically to unset.
- Non-empty prefix prepends correctly to all six generators, including
the suffix-style symgraph names.
- Two different prefixes produce disjoint collection-name sets for the
same projectId (the multi-instance isolation property).
- Validation rejects whitespace, slash, colon, and unicode characters.
- The error message includes the offending value for discoverability.
- Validation accepts the full set of legal characters.
Existing 752 unit tests continue to pass unchanged. Total: 772.
typecheck, biome, and CodeRabbit local review all clean. README
updated to document the new env var alongside the other QDRANT_*
settings, including the user-side responsibility to remove old
collections when changing prefix between runs.
Co-authored-by: awbait <awbait@users.noreply.github.com>
LM Studio's Local Server speaks the OpenAI-compatible /v1/embeddings
protocol, so users running it as their model host (chat plus embedding in
one desktop app, GGUF model management) had no clean integration path.
Changes:
- src/services/provider-lmstudio.ts: new LMStudioEmbeddingProvider wrapping
the OpenAI SDK with a custom baseURL (default http://localhost:1234/v1).
Sends a placeholder API key to satisfy the OpenAI SDK while LM Studio's
Local Server runs without auth by default. Skips the dimensions parameter
because LM Studio models have no Matryoshka projection. Forces
encoding_format=float to defeat the OpenAI SDK 6.x base64 default, which
would otherwise mangle LM Studio's plain-array responses into 1024 zeros.
- src/services/embedding-config.ts: extends the EmbeddingProvider union,
reads LMSTUDIO_URL and LMSTUDIO_API_KEY, fail-fast validation when
EMBEDDING_PROVIDER=lmstudio without EMBEDDING_MODEL or EMBEDDING_DIMENSIONS.
- src/services/embedding-provider.ts: factory case for lmstudio with a
dynamic import to avoid loading the OpenAI SDK at startup for ollama users.
- ensureReady distinguishes "LM Studio unreachable" from "reachable but
embedding model not loaded" so the operator knows whether to start the
Local Server or load the configured model.
- src/services/qdrant.ts: minor refactor to extract the hybrid-search query
payload to a local const for readability.
- README.md: dedicated LM Studio section, MCP host config example, env-var
table entries.
- tests/unit/embedding-config.test.ts: 8 new cases (required-env validation,
URL default and override, optional API key, context-length override).
- tests/unit/embedding-provider.test.ts: 3 new cases (factory wiring,
ensureReady error format against a closed port, healthCheck unreachable
output).
Backward compatible. The lmstudio provider is opt-in via
EMBEDDING_PROVIDER=lmstudio. Existing ollama, openai, and google paths are
untouched.
shields.io's `visual-studio-marketplace/*` endpoints currently return
"404: badge not found", so the version and installs badges on the
extension's marketplace listing render as broken images. Switch to
`vsmarketplacebadges.dev`, which is the de-facto third-party
replacement most VS Code extensions fall back to.
Also surface the marketplace listings in the root README's top badge
row, alongside the existing MCP-install deep-link badges. The two
serve different purposes (the deep links register the MCP config
without an extension, the marketplace badges link to the extension
itself), so both stay.
A pass over the extension surface to address review feedback:
Safety / hardening:
- `graphPanel.ts`: validate `m.path` from the webview before opening
files. Reject absolute paths and any path that escapes the workspace
root (`..`, `/foo`, `C:/...`). Validate the line number is a positive
integer before constructing a `Range`. Surface failures via the output
channel rather than letting the rejection bubble up.
- `mcpProvider.ts`: defensively check that
`vscode.lm.registerMcpServerDefinitionProvider` exists before calling
it. The `engines.vscode: ^1.99.0` field already enforces this on
install, but some VS Code-derived editors mis-report their engine
version. The extension now degrades gracefully (sidebar, commands,
status bar still work) instead of failing activation.
- `commands.ts` and `graphPanel.ts`: wrap `workbench.action.chat.open`
in try/catch. Not every VS Code-compatible editor exposes that
command; falling back to the output channel avoids unhandled
rejections after the user clicked "Open chat".
- `extension.ts`: persist the first-run walkthrough flag only after the
walkthrough command resolves successfully, so a transient failure
doesn't silently skip the onboarding forever.
CI gates:
- `extension-ci.yml` and `extension-release.yml`: run `npm test` between
typecheck and build, so manifest-level smoke regressions can't slip
through to either the PR artefact or the marketplace publishes.
Settings copy:
- `socraticode.env` description: explicitly call out that the setting
is for non-secret config only. Recommend OS environment variables /
local `.env` files for API keys, since workspace settings can sync
via Settings Sync and end up in committed `.vscode/settings.json`.
Quality of life:
- `sidebar.ts` `formatRelative`: clamp the computed seconds to zero so
a file mtime slightly ahead of the local clock doesn't render
"-5s ago".
- `walkthroughs/first-index.md`: corrected the embedding model name
(`nomic-embed-text`, not `mxbai-embed-large`) to match the engine
default in `src/constants.ts`.
Lint / docs:
- `extension/README.md`: hyphenate "Eclipse Theia-based editors".
- `DEVELOPER.md`: add `text` language hint to the directory-tree code
fence (markdownlint MD040). Updated the inline comment for
`settings.ts` to reflect its current shape.
- `README.md`: reflow the "extension vs plugin" callout into a single
blockquote (markdownlint MD028).
Lint, typecheck, manifest tests and build all clean. Engine unit tests
unaffected (706/706 still pass).
README updates:
- Plugins table now includes a row for the VS Code / Open VSX extension,
with a list of every editor that pulls from one of the two registries
(Cursor, VSCodium, Gitpod, code-server, Theia, Antigravity, Particle
Workbench).
- Cursor Marketplace listing mentioned alongside the existing
`/add-plugin` URL install.
- A short "extension vs plugin" callout explaining when to install
which: the extension auto-registers MCP and adds native UI, the
plugin formats add skills + agent rules. Both can coexist.
DEVELOPER.md updates:
- New "VS Code / Open VSX Extension" section covering layout, local
development (F5 to launch an Extension Development Host), build /
lint / test / package commands, publishing flow, and versioning
policy (extension tracks the engine version via the bump script).
- Explicit list of what the extension is NOT (no re-implementation of
search, no shipped engine, no language-server features). Keeps scope
honest and prevents future feature creep.
- Added the new section to the table of contents.
Address CodeRabbit findings on PR #36:
1. The previous patch attached `QDRANT_API_KEY` as an `api-key` header
regardless of URL scheme, which would leak the secret on the wire if
a user configured an authenticated Qdrant over plain HTTP. Add a
guard that rejects the combination and throws a specific error,
placed before the readiness probe so its message is not masked by
the generic "Cannot reach external Qdrant" handler. Loopback URLs
(`localhost`, `127.0.0.1`, `[::1]`) are accepted on `http://` so
local-dev workflows where users run authenticated Qdrant on plain
HTTP keep working. The URL is parsed (rather than checked with
startsWith) so hostnames like `http://localhost.evil.com` are not
mistaken for loopback.
2. The "omits api-key header when QDRANT_API_KEY is not set" test
relied on the spread of the real `constants.js` module, which means
it would flake to a header-attached state on any developer machine
with `QDRANT_API_KEY` exported in the shell. Pass
`QDRANT_API_KEY: undefined` explicitly so the override always wins.
3. Add two tests covering the new guard: one asserting the rejection
on plain HTTP for non-loopback hosts, and one asserting that the
localhost exception still attaches the api-key header.
4. Document the HTTPS requirement (and localhost exception) in the
`QDRANT_API_KEY` row of the README configuration table.
- Add "Portable, AI- and host-agnostic" paragraph in the intro that
bundles two claims: the codebase context lives with the code (works
with any assistant / IDE / CLI, any combination), and pre-computed
reasoning (blast radius, call-flow, dependency traversal) lets
smaller / cheaper models hold their own on architectural questions.
- Add three rows to the "Built-in Code Search vs SocratiCode"
comparison table: symbol-level impact / blast radius, call-flow
tracing, interactive visual graph explorer.
- Plugins section: chain Claude Code's two install commands with &&
so the row is a single copy-paste — the install step was missing.
Interactive Viewer (primary)
────────────────────────────
codebase_graph_visualize now accepts mode="mermaid" (default, existing
behaviour — text Mermaid diagram) or mode="interactive". Interactive
mode generates a self-contained HTML page and opens it in the user's
default browser via the `open` npm package (cross-platform: macOS,
Linux, Windows). Cytoscape.js 3.30.2 + Dagre 0.8.5 + cytoscape-dagre
2.5.0 are vendored under src/assets/ — no CDN, works offline.
Features:
- File view — every source file as a node, imports as edges, language
colour-coded, circular deps highlighted in red.
- Symbol view toggle — functions/classes/methods as nodes with call
edges (confidence-styled). Embedded when the symbol graph fits under
20k symbols / 60k call edges; above that threshold the file view
remains usable and a banner directs users to codebase_impact /
codebase_symbols for symbol-level queries.
- Sidebar on node click — imports, dependents, per-file symbol list
(first 30 + link to codebase_symbols), action buttons for blast
radius and call flow.
- Right-click any node → blast radius overlay (reverse-transitive
closure). Call-flow button on the sidebar for forward traversal.
- Live search across files and symbols, six Cytoscape layouts
(Dagre / force / concentric / breadth-first / grid / circle),
PNG export (filename sanitised for cross-platform safety).
- `open: false` parameter skips auto-launch and just returns the file
path — useful in headless environments.
Viewer is XSS-safe by construction: all DOM built with createElement
+ textContent (no innerHTML anywhere); embedded JSON escapes every
"<" as \u003c so a stray </script> in a file path or symbol name
cannot break out of the script-type="application/json" container.
New files:
- src/assets/{cytoscape.min.js,dagre.min.js,cytoscape-dagre.js,
viewer-template.html,viewer-styles.css,viewer-app.js}
- scripts/copy-assets.mjs — postbuild copier (tsc does not handle
non-TS files); wired into npm run build and prepublishOnly
- src/services/graph-visualize-html.ts — HTML builder with scale-cap
logic (MAX_SYMBOLS / MAX_EDGES / MAX_SYMS_PER_FILE) and parallel
per-file Qdrant payload loading
- src/services/graph-visualize-browser.ts — temp-file write +
cross-platform open wrapper
- tests/unit/graph-visualize-html.test.ts — 5 tests (self-contained,
escape-safety, symbolMode omitted/capped, cycle marking)
- tests/unit/graph-visualize-browser.test.ts — 4 tests (deterministic
path, overwrite, success + failure paths)
New runtime dependency: open@^10.2.0 (Sindre Sorhus, zero transitive
deps, cross-platform).
British-English doc sweep (secondary)
─────────────────────────────────────
Switched all project docs to British English spelling:
behavior → behaviour organized → organised
color-coded → colour-coded initialization → initialisation
visualization → visualisation customization → customisation
recognized → recognised optimized → optimised
acknowledgment → acknowledgement finalize → finalise
analyzing → analysing apologizing → apologising
sexualized → sexualised
Affected files: README, DEVELOPER, AGENTS, CLAUDE, GEMINI, SECURITY,
CONTRIBUTING, CODE_OF_CONDUCT, agents/codebase-explorer.md,
skills/codebase-exploration/{SKILL.md,references/tool-reference.md},
skills/codebase-management/references/tool-reference.md.
Also surfaced Impact Analysis in the top-level README paragraph.
Docs
────
- README: "Interactive graph explorer" subsection under Impact Analysis,
tool-table row updated.
- DEVELOPER.md: architecture section under codebase_graph_visualize
covering asset layout, data flow, cap logic, XSS-safety invariants.
- AGENTS.md / CLAUDE.md / GEMINI.md: new "User asks for a visual /
interactive / shareable graph" row in the tool-routing table.
- skills/codebase-exploration/: SKILL.md bullet + tool-reference.md
full mode description.
- CHANGELOG.md: "Interactive Graph Explorer" section under Unreleased.
Quality gates (all green)
─────────────────────────
- Biome lint: clean
- TypeScript (tsc): clean
- Unit tests: 685/685
- Integration tests: 154/154 (real Qdrant + Ollama)
- CodeRabbit: No findings (1 fix applied — filename sanitisation)
- Snyk code test: 0 issues
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- 4 new unit test files (22 tests) for graph-symbols, graph-symbol-resolution,
graph-entrypoints, symbol-graph-cache. All 799 tests pass.
- README/AGENTS/CLAUDE/GEMINI: document codebase_impact, codebase_flow,
codebase_symbol, codebase_symbols and updated workflow guidance.
- DEVELOPER.md: new architectural section for symbol-level call graph,
including sharded storage layout and resolution confidence levels.
- CHANGELOG: Unreleased section for the impact-analysis feature.
- Apply CodeRabbit fixes: dedupe in-flight cache loads, set ImpactResult.truncated
when frontier extends beyond depth limit, drop redundant String() around Lang enum.
- Switch reverse-shard hash from SHA1 to SHA256 (Snyk hardening; non-cryptographic use).
- README: new Features entries, full sections with config examples
- README: new env vars SOCRATICODE_BRANCH_AWARE, SOCRATICODE_LINKED_PROJECTS
- README: updated codebase_search tool description for includeLinked
- DEVELOPER.md: updated config.ts description, branch-aware and linked projects sections
- Move Svelte/Vue from "Indexing Only" to "Full Support" in README
- Move SASS/LESS to "Code Graph via Regex" in README
- Add graph-aliases.ts to DEVELOPER.md service file listing
- Update DEVELOPER.md data flow with CSS @import, path alias, and SCSS
partial resolution steps
- Add .claude-plugin/plugin.json with MCP server reference and hooks
- Add codebase-exploration skill with search-before-reading workflow
- Add codebase-management skill with indexing and troubleshooting guides
- Add codebase-explorer delegatable subagent for deep analysis
- Add SessionStart hook for duplicate MCP detection
- Add .mcp.json for plugin-bundled MCP server config
- Update package.json files array to include plugin assets in npm package
- Add release-it after:bump hook to sync plugin.json version
- Update README with plugin install badge, instructions, and guidance
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.
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.
Highlight that multiple AI agents can share a single index on the same
codebase with automatic coordination. Added to the intro paragraph,
Why SocratiCode, Features list, and FAQ.
Tomasz Szuster