The Problem
AI coding assistants struggle with large codebases. They either rely on grep-style retrieval that misses semantic relationships, or they dump entire files into context and blow through token limits. On enterprise repositories with tens of millions of lines, this makes AI assistance slow, expensive, and often wrong. Teams need a way to give AI tools structured, queryable knowledge of their code without manual configuration or sending code to third-party services.
What This Does
SocratiCode is a local, zero-configuration context engine that indexes a codebase and exposes it to AI assistants through the Model Context Protocol (MCP) or native plugins for Claude Code, Cursor, VS Code Copilot, Codex, and Gemini CLI. The core indexer in src/services/indexer.ts builds a hybrid semantic index backed by Qdrant (src/services/qdrant.ts) and a polyglot dependency graph (src/services/code-graph.ts). A file watcher (src/services/watcher.ts) keeps the index current as code changes.
The system exposes five tool groups in src/tools/: query-tools.ts for hybrid search, graph-tools.ts for dependency traversal, index-tools.ts for index management, context-tools.ts for database/API/infra artifacts, and manage-tools.ts for lifecycle operations. Embedding providers are pluggable (src/services/embedding-provider.ts) with OpenAI, Ollama, and Google backends. Everything runs locally by default via Docker Compose, with indexing checkpoints that survive crashes and restarts.
How To Use It
Setup: Install via npm (socraticode package) or run from source with npm install followed by npm run build (inferred from package.json). The docker-compose.yml provisions Qdrant and Ollama locally.
Configuration: No environment variables are required. Embedding provider selection and model settings live in src/services/embedding-config.ts with sensible defaults. Optional ignore rules go in .socraticodeignore, mirroring .gitignore syntax.
Running it: Start the MCP server with npx socraticode — this is the documented command in the README's install badges. The entry point is src/index.ts. Install as an MCP server in any host, or use the one-click plugin installers for Claude Code, Cursor, and VS Code.
Install the package
npm install -g socraticode
Start the MCP server (auto-provisions Docker containers on first run) npx socraticode
Real-World Use
A team with a 5-million-line monorepo adds SocratiCode to Claude Code via the plugin installer. When an engineer asks "where does the payment flow validate webhook signatures and what tables does it touch?", the assistant uses query-tools.ts for semantic search, graph-tools.ts to trace the call chain, and context-tools.ts to pull the relevant DB schema — all without the engineer writing a single query or the code leaving their machine.
Code Health & Issues
Med - Docker dependency: The default setup requires Docker for Qdrant and Ollama. Teams without Docker on developer machines face friction, though the provider abstraction (src/services/provider-*.ts) suggests alternatives exist. Low - Plugin fragmentation: Five separate plugin directories (.claude-plugin, .cursor-plugin, .codex-plugin, etc.) mean configuration drift risk across plugin formats. The hooks/hooks.json and multiple marketplace.json files compound this. Low - Single maintainer trajectory: The original repo has 3,247 stars but this fork shows 0. Verify upstream activity and maintenance commitment before adopting. Positive signals: 35 test files across unit/integration/e2e, CI in .github/workflows/ci.yml, dual AGPL/commercial licensing, and a clean dependency tree with lockfile.
The Bottom Line
SocratiCode fills a real gap: it gives AI assistants structured codebase intelligence without cloud dependencies or setup overhead. The architecture is sound, the testing is solid, and the 61% token reduction claim is plausible given the hybrid search design. It's best suited to teams working on large codebases with AI-assisted development workflows; small projects likely won't justify the Docker overhead. Verify upstream maintenance before committing, but the design and execution are credible.