giancarloerra/SocratiCode

SocratiCode – Code‑base‑aware AI engine

What it is – SocratiCode is an open‑source code‑base context engine that lets any LLM (Claude, OpenAI, Gemini, etc.) understand the full semantics of a repository without the model having to read every file at query time. It builds a local index (embeddings + AST‑aware chunks, dependency graphs, symbol‑level impact data) and serves it through the MCP (Multi‑Chat‑Protocol) interface used by Claude Code, OpenAI Codex, VS Code, Cursor, Gemini CLI and other hosts.

Why it matters – Large codebases (tens of millions of lines) are expensive to feed to LLMs: token cost, latency, and hallucinations. SocratiCode pre‑computes the heavy lifting once, then lets the assistant retrieve exact symbols, call‑flows, and related artefacts (DB schemas, API specs, infra configs) in a few milliseconds. This reduces context size, token usage and tool calls, and enables smaller, cheaper models to perform architectural‑level reasoning.

---

Core features (as described in the README)

• Hybrid search – combines semantic (embedding) and BM25 (keyword) retrieval with reciprocal‑rank‑fusion.
• Polyglot dependency graphs – parses 18 languages, builds a symbol‑level call‑flow / blast‑radius graph, visualised in an interactive HTML explorer.
• Impact analysis – trace what functions, classes or files would be affected by a change.
• Context artefacts – index and make searchable DB schemas, OpenAPI specs, Terraform/Cloud configs, architecture docs, etc.
• Zero‑configuration start – npx socraticode@latest launches a Docker stack (Qdrant vector DB + Ollama for local embeddings) automatically.
• Automatic incremental indexing – file‑watcher updates the index on every change; resumable checkpoints survive crashes.
• Multi‑repo / multi‑branch / multi‑agent – a single index can be shared by many AI agents concurrently.
• Private‑by‑default – everything runs locally; no API keys are needed unless you opt‑in to cloud embeddings (OpenAI, Google Gemini) or an external Qdrant instance.
• Cloud‑ready – SocratiCode Cloud (private beta) adds SSO, audit logs, branch‑aware indexing and VPC/air‑gapped deployment while keeping the core engine free.
• Extensive host integrations – native plugins for Claude Code, OpenAI Codex, VS Code (agent plugin & editor extension), Cursor, Gemini CLI, Continue, Cline, Zed, OpenCode, plus a direct‑MCP mode.
• Benchmarked performance – on a 2.45 M‑line VS Code project it used 61 % less context, 84 % fewer tool calls and was 37× faster than a grep‑based workflow (Claude Opus 4.6).

---

Getting started (quick‑start flow)

1. Prerequisites – Node ≥ 18.17, npx on PATH, Docker running (for the default Qdrant + Ollama stack).
2. Install – the simplest path is via an MCP host:

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

   Or use the one‑click badge for Claude Code, VS Code, or Cursor (the README provides badge links that trigger the same npx command).
3. First index – in your chat, ask the assistant “Index this codebase”. SocratiCode runs in the background, watches the repository and reports progress via codebase_update / codebase_watch commands.
4. Use – once indexed you can:
   • codebase_search { query: "…" } – hybrid semantic + BM25 search.
   • codebase_graph { symbol: "MyClass.method" } – view the dependency graph.
   • codebase_impact { symbol: "…" } – get blast‑radius analysis.
   • Query artefacts like schema_search, api_spec_search, etc.
5. Keep up‑to‑date – the engine updates automatically on each MCP server start (npm @latest). Plugins/extensions update through the host’s normal extension‑update mechanisms.

---

Typical workflow example

User:  Index this codebase.
Assistant (via SocratiCode):  Indexing started… 45 % done.
User:  What function reads the `config.yaml` file?
Assistant:  (runs `codebase_search` → returns `loadConfig` in `src/config.ts`)
User:  Show me the call‑flow from `loadConfig`.
Assistant:  (runs `codebase_graph` → displays interactive HTML graph)
User:  Which modules would be affected if I change `Database.connect`?
Assistant:  (runs `codebase_impact` → lists dependent services, tests, docs)

All of the heavy analysis is performed locally; the LLM only receives the concise results.

---

Configuration highlights

• Embedding provider – EMBEDDING_PROVIDER can be ollama (default, local), openai, or google. Set the appropriate API keys via environment variables.
• Watcher mode – SOCRATICODE_WATCHER=off|manual|auto controls automatic file‑watch updates.
• Resume behaviour – SOCRATICODE_AUTO_RESUME_PROJECTS / SOCRATICODE_AUTO_RESUME let you pre‑load multiple repositories.
• Version pinning – set SOCRATICODE_SPEC to a concrete npm version (e.g., socraticode@1.14.0) to freeze the engine across restarts.
• Docker resources – the README explains how to allocate CPU/RAM to the Qdrant/Ollama containers for large repos.

---

Who should use it

• Developers who want their LLM assistants (Claude, ChatGPT, Gemini, etc.) to reason about a monorepo, micro‑service architecture or infrastructure‑as‑code without exposing source to external services.
• Teams building internal AI‑powered dev‑ops tools, code‑review bots, or automated impact‑analysis pipelines.
• Enterprises needing a self‑hosted, policy‑controlled code‑intelligence layer (see the sibling project JanuScope for MCP governance, PII redaction, rate‑limiting, etc.).

---

License & community

• License: AGPL‑3.0 (full source available, commercial use requires compliance with AGPL).
• Community: Discord server for support, GitHub issues for bugs/feature requests, and a private‑beta hosted SaaS offering (SocratiCode Cloud) for teams that want managed hosting with SSO and audit logs.

---

Bottom line

SocratiCode turns any LLM into a code‑aware assistant by building a local, up‑to‑date index of your entire repository and exposing powerful search, graph and impact‑analysis tools through a standard MCP interface. It’s designed for zero‑config, privacy‑first deployment at enterprise scale, while remaining usable for a single developer via one‑click VS Code or Claude Code plugins.