SocratiCode

// Overview

SocratiCode indexes a repository once and then answers structural questions about it over the Model Context Protocol, so any assistant that speaks MCP — Claude Code, Codex, VS Code, Cursor, Gemini CLI, Continue, Cline, Roo Code, Zed, OpenCode — queries the same index. That is the project's central argument against the codebase features built into individual editors: the index is not tied to whichever tool you happen to be using this month.

Retrieval is hybrid. Dense vectors and BM25 keyword matching are combined with reciprocal rank fusion for search, and on top of that sits a dependency graph built from AST parsing across nineteen or more languages, with a line-based fallback for anything unparsed. That graph is what makes the structural tools possible: `codebase_impact` gives the blast radius of changing a symbol, `codebase_flow` traces a call path from an entry point, `codebase_graph_circular` finds dependency cycles, and `codebase_graph_visualize` emits a Mermaid diagram. Database schemas, API specs and infrastructure config are indexed alongside the code.

It is designed to sit on large repositories without hand-holding. Indexing is incremental and resumable from checkpoints, a file watcher keeps the index current as you work, separate indexes are kept per git branch, and linked projects can be searched together. The maintainers report that on the VS Code codebase — around 2.45 million lines, driven by Claude Opus 4.6 — this used 61% less context and 84% fewer tool calls than grep-based exploration, and was 37x faster; those figures are the project's own measurements. The default stack runs locally in Docker with Qdrant for vectors and Ollama for embeddings, with OpenAI, Gemini, LM Studio and LiteLLM available as alternatives. The code is AGPL-3.0, with a commercial licence offered separately.

// What it does

• Hybrid retrieval combining dense vectors and BM25 with reciprocal rank fusion
• Polyglot dependency graph from AST parsing across 19+ languages, with Mermaid visualisation and circular-dependency detection
• Symbol-level impact analysis and call-flow tracing — blast radius for a change, callers and callees for a function
• Branch-aware indexes, cross-project search over linked repositories, and indexing of schemas, API specs and infrastructure files
• Incremental, checkpoint-resumable indexing plus a live file watcher that keeps the index in step with edits
• Local-by-default stack (Qdrant and Ollama in Docker), with OpenAI, Google, LM Studio or a LiteLLM proxy as embedding providers

// Getting started

SocratiCode runs through `npx`, so there is nothing to install globally. It needs Node.js 18.17 or newer and a running Docker daemon for the default Qdrant and Ollama stack. Installation is really just registering it as an MCP server with your assistant.

claude plugin marketplace add giancarloerra/socraticode
claude plugin install --scope user socraticode@socraticode

{
  "mcpServers": {
    "socraticode": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"]
    }
  }
}

gemini extensions install https://github.com/giancarloerra/socraticode --auto-update

EMBEDDING_PROVIDER=openai      # or ollama (default), google, lmstudio, litellm
QDRANT_MODE=external           # or managed (default), cloud
SOCRATICODE_BRANCH_AWARE=true
SOCRATICODE_WATCHER=auto

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Giving an agent a map of a repository too large for it to read its way around
• Answering "what breaks if I change this function" before starting the change
• Keeping one index when the team uses several different assistants and editors
• Searching code, database schemas and API specs together when tracing how a field flows through a system

// How SocratiCode compares

SocratiCode alongside other open-source code indexing & search tools AI/TLDR tracks, ranked by GitHub stars.