SocratiCode

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

Give any AI instant automated knowledge of your entire codebase (and infrastructure) — at scale, zero configuration, fully private, completely free.

Kindly sponsored by <a href="https://altaire.com">Altaire Limited</a>

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!

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, polyglot code dependency graphs, and searchable context artifacts (database schemas, API specs, infra configs, architecture docs). Zero configuration — add it to any MCP host, or install the Claude Code plugin for built-in workflow skills. 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-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.

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 visualization, 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 →

Quick Start
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
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 the first run. To get the latest version, clear the cache and restart your MCP host: rm -rf ~/.npm/_npx && claude mcp restart socraticode. Alternatively, use npx -y socraticode@latest in your config to always check for updates on startup (slightly slower).

OpenAI Codex CLI — add to ~/.codex/config.toml:

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "socraticode"]

Restart your host. On first use SocratiCode automatically pulls Docker images, starts its own Qdrant and Ollama containers, and downloads the embedding model — one-time setup, ~5 minutes depending on your connection. After that, it starts in seconds.

First time on a project — ask your AI: "Index this codebase". Indexing runs in the background; ask "What is the codebase index status?" to monitor progress. Depending on codebase size and whether you're using GPU-accelerated Ollama or cloud embeddings, first-time indexing can take anywhere from a few seconds to a few minutes (it takes under 10 minutes to first-index +3 million lines of code on a Macbook Pro M4). Once complete it doesn't need to be run again, you can search, explore the dependency graph, and query context artifacts.

Every time after that — just use the tools (search, graph, etc.). On server startup SocratiCode automatically detects previously indexed projects, restarts the file watcher, and runs an incremental update to catch any changes made while the server was down. If indexing was interrupted, it resumes automatically from the last checkpoint. You can also explicitly start or restart the watcher with codebase_watch { action: "start" }.

macOS / Windows on large codebases: Docker containers can't use the GPU. For medium-to-large repos, install native Ollama (auto-detected, no config change needed) for Metal/CUDA acceleration, or use OpenAI embeddings for speed without a local install. Full details.

Recommended: For best results, add the Agent Instructions to your AI assistant's system prompt or project instru

SocratiCode

Install / Use

README

SocratiCode

Contents

Quick Start