socraticode

SocratiCode

"There is only one good, knowledge, and one evil, ignorance." — Socrates

Your AI reads code. SocratiCode understands it.

The open-source codebase context engine: give any AI instant automated knowledge of your entire codebase (and infrastructure) — at scale, zero configuration, fully private, completely free.

🛡️ Need MCP governance together with codebase context? See our sibling project JanuScope — the local-first MCP policy proxy: tool blocking, SQL-mutation gate, PII redaction, audit, rate-limit.

If SocratiCode has been useful to you, please ⭐ star this repo — it helps others discover it — and share it with your dev team and fellow developers!

💬 Questions or just want to chat? Join us on Discord.

☁️ SocratiCode Cloud (private beta) — Hosted, shared team index built on the same engine as the open-source version, plus SSO, audit logs, branch-aware indexing, and VPC / air-gapped deployment options. The open-source core remains free forever. Request early access →

One thing, done well: deep codebase intelligence with zero setup, no bloat, and full automation. SocratiCode gives AI assistants deep semantic understanding of your codebase: hybrid search, cross-project search, polyglot code dependency graphs, symbol-level impact analysis and flow, interactive HTML graph explorer for visual navigation, and searchable context artifacts (database schemas, API specs, infra configs, architecture docs). Zero configuration: add it to an MCP host that supports local stdio servers, or use a supported plugin or extension. It manages everything automatically.

Production-ready, battle-tested on enterprise-level large repositories (up to and over ~40 million lines of code). Batched, automatic resumable indexing checkpoints progress — pauses, crashes, restarts, and interruptions don't lose work. The file watcher keeps the index automatically updated at every file change and across sessions. Multi-branch, multi-repo and multi-agent ready — multiple AI agents can work on the same codebase simultaneously, sharing a single index with automatic coordination and zero configuration.

Private and local by default — Docker handles everything, no API keys required, no data leaves your machine. Cloud ready for embeddings (OpenAI, Google Gemini) and Qdrant, and a full suite of configuration options are all available when you need them.

Code intelligence that belongs to you, AI and host agnostic — your codebase's understanding lives with the code, not locked to any one assistant, IDE or model. And because SocratiCode pre-computes the hard parts (blast radius, call-flow, dependency traversal), smaller models can handle architectural complex tasks that would otherwise need top-tier reasoning, saving even more on token cost.

The first Qdrant‑based MCP/Claude Plugin/Skill that pairs auto‑managed, zero‑config local Docker deployment with AST‑aware code chunking, hybrid semantic + BM25 (RRF‑fused) code search, polyglot dependency graphs with circular‑dependency visualisation, symbol‑level Impact Analysis (blast‑radius & call‑flow tracing across 18 languages), and searchable infra/API/database artifacts in a single focused, zero-config and easy to use code intelligence engine.

Benchmarked on VS Code (2.45M lines): SocratiCode uses 61% less context, 84% fewer tool calls, and is 37x faster than grep‑based exploration — tested live with Claude Opus 4.6. See the full benchmark →

Contents

• Quick Start
• Plugins and host integrations
• Why SocratiCode
• Features
• Prerequisites
• Example Workflow
• Agent Instructions
• Configuration
• Language Support
• Ignore Rules
• Context Artifacts
• Environment Variables
• Docker Resources
• Testing
• Why Not Just Grep?
• FAQ
• Community
• SocratiCode Cloud
• License

---

Quick Start

Requirements: Node.js 18.17 or newer with npx on PATH, plus Docker running for the default local Qdrant and Ollama stack.

Quick install guidance for Claude Code, VS Code, and Cursor:

MCP hosts with a JSON mcpServers object can use this complete configuration:

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

Configuration schemas are host-specific. Continue, VS Code, Zed, OpenCode, Gemini CLI, Cline, and Roo Code have dedicated examples in Plugins and host integrations.

Keeping SocratiCode up to date

SocratiCode has two independent update paths. The MCP engine is the socraticode package published to npm. Every npm-backed configuration below uses npx -y --prefer-online socraticode@latest, which checks npm for the current latest release whenever the MCP server starts. A running server cannot replace itself, and a newly published version can only be downloaded while the npm registry is reachable, so restart or reconnect the server after a release.

Native plugins and extensions also contain skills, instructions, manifests, or UI files. Update those through the host as shown below, then start a new session so the new plugin files load. Direct MCP installations contain only the engine and do not install SocratiCode's plugin skills.

Integration	Update plugin, skills, and integration files
Claude Code plugin	Enable marketplace auto-update, or run claude plugin marketplace update socraticode followed by claude plugin update --scope user socraticode@socraticode
OpenAI Codex plugin	Run codex plugin marketplace upgrade socraticode, then codex plugin add socraticode@socraticode and start a new task
VS Code Agent Plugin	Leave extensions.autoUpdate enabled for daily checks, or run Extensions: Check for Extension Updates, then start a new Chat
VS Code editor extension	Update it through the Extensions view or Extensions: Check for Extension Updates, then reload the window
Cursor local plugin	Update to the latest GitHub release tag using the commands in the Cursor section, then reload Cursor
Gemini CLI extension	Install with --auto-update, or run gemini extensions update socraticode, then restart Gemini
Direct MCP only	No separate plugin files are installed; restart or reconnect the MCP server to resolve the current npm release

@latest refers to npm's published latest distribution tag; it does not refer to a Git branch. --prefer-online forces npm to check for updated package metadata even when its cache is still fresh. If the same registry is temporarily unavailable, npm can still use an already populated cache; a first installation still requires registry access. See the npm exec cache documentation and npm distribution-tag documentation.