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 — zero setup, no bloat, fully automatic. 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 any MCP host, or install the Native Plugin for Claude Code, Cursor, VS Code Copilot, Codex or Gemini CLI. 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
• 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

Only Docker (running) required.

One-click install — Claude Code, VS Code and Cursor:

All MCP hosts — add the following to your mcpServers (Claude Desktop, Windsurf, Cline, Roo Code) or servers (VS Code project-local .vscode/mcp.json) config:

"socraticode": {
  "command": "npx",
  "args": ["-y", "socraticode"]
}

Claude Code — install the plugin (recommended, includes workflow skills for best results):

From your shell:

claude plugin marketplace add giancarloerra/socraticode
claude plugin install socraticode@socraticode

Or from within Claude Code:

/plugin marketplace add giancarloerra/socraticode
/plugin install socraticode@socraticode

Auto-updates: After installing, enable automatic updates by opening /plugin → Marketplaces → select socraticode → Enable auto-update.

Or as MCP only (without skills):

claude mcp add socraticode -- npx -y socraticode

Updating: npx caches the package after th