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.

Restart your host. With the default local configuration, first use pulls the required Docker images and starts managed Qdrant. OLLAMA_MODE=auto reuses a detected native Ollama instance or starts managed Ollama, then downloads the local embedding model if it is not already available. Cloud and external embedding providers do not download a local model. Initial setup usually takes about five minutes, depending on the connection; later starts take 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.). By default, server startup resumes the indexed project represented by the MCP process's working directory: a complete index gets its watcher and an incremental catch-up update, while interrupted indexing resumes from the last checkpoint. SOCRATICODE_AUTO_RESUME_PROJECTS and SOCRATICODE_AUTO_RESUME=all can select additional projects. A completed indexed project not handled at startup gets a fallback watcher start on its first search, status, or graph interaction. You can also explicitly start or restart the watcher with codebase_watch { action: "start" }.

Prefer a deliberate index snapshot? Set SOCRATICODE_WATCHER=off and SOCRATICODE_AUTO_RESUME=off for every MCP process that uses the checkout, then run codebase_update only when you want to refresh it. Existing indexes remain usable without rebuilding. Use SOCRATICODE_WATCHER=manual instead if explicit codebase_watch { action: "start" } should remain available. See Indexing Behaviour and Passing env vars by host.

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 instructions file (CLAUDE.md, AGENTS.md, etc.). The key principle, search before reading, helps your AI use SocratiCode's tools effectively and avoid unnecessary file reads.

Claude Code users: If you installed the SocratiCode plugin, the Agent Instructions are included automatically as skills, so there is no need to add them to your CLAUDE.md. The plugin also bundles the MCP server, so you don't need a separate claude mcp add.

Advanced: cloud embeddings (OpenAI / Google), external Qdrant, remote Ollama, native Ollama, and dozens of tuning options are all available. See Configuration below.

Plugins and host integrations

SocratiCode can be installed as a native agent plugin, a VS Code editor extension, a Gemini CLI extension, or a directly configured local stdio MCP server. These are separate integration types and use different configuration and update paths.

Every path below requires Node.js 18.17 or newer with npx on PATH. The default local stack also requires Docker to be running. Docker is optional when Qdrant is external and embeddings use either a detected native Ollama instance or a cloud or external provider.

Host	Recommended integration	Scope
Claude Code	Native plugin	User
OpenAI Codex	Native plugin	User
VS Code	Agent Plugin or editor extension	Current VS Code profile
Cursor	Local Cursor plugin or direct MCP	User or project
Gemini CLI	Gemini extension	User
Continue	Direct MCP	Project or user config
Cline	Direct MCP	Project or user config
Roo Code	Direct MCP	Project or user config
Zed	Direct MCP	User or project settings
OpenCode	Direct MCP	Project or user config

Claude Code plugin (recommended for Claude Code users)

The native plugin bundles the MCP server, workflow skills, and agent instructions. Install it for the current user:

claude plugin marketplace add giancarloerra/socraticode
claude plugin install --scope user socraticode@socraticode
claude plugin list

Start a new Claude Code session after installation. Existing sessions do not load a newly installed plugin. To enable automatic updates, open /plugin, select Marketplaces, select socraticode, and enable auto-update. To update manually:

claude plugin marketplace update socraticode
claude plugin update --scope user socraticode@socraticode

Run /reload-plugins or start a new session after updating. If SocratiCode was previously added as a standalone MCP server, remove that duplicate with claude mcp remove socraticode; the plugin already provides the server.

For custom providers or external Qdrant, put inherited variables in Claude Code's user settings and restart the session:

{
  "env": {
    "EMBEDDING_PROVIDER": "openai",
    "OPENAI_API_KEY": "<your key>"
  }
}

Keep this user-scoped file private, or provide secrets through the process environment. Never commit secret values.

See the Claude Code plugin documentation.

Claude Code MCP-only installation

For a user-scoped installation without the bundled skills:

claude mcp add --scope user socraticode -- npx -y --prefer-online socraticode@latest
claude mcp list

Start a new session, or run /mcp and select Reconnect. The explicit @latest command checks for the latest published engine each time the server starts. claude mcp add defaults to project-local scope when --scope user is omitted. See the Claude Code MCP documentation.

OpenAI Codex plugin

The Codex plugin bundles SocratiCode's MCP server, skills, and instructions. Add the Git marketplace and install the plugin for the current user:

codex plugin marketplace add giancarloerra/socraticode --ref main
codex plugin add socraticode@socraticode
codex plugin list --available --json

Start a new Codex task or CLI session after installation. Reopening an existing task does not load newly installed skills or MCP tools. Update and verify with:

codex plugin marketplace upgrade socraticode
codex plugin add socraticode@socraticode
codex plugin list --available --json

Codex has a public plugin directory, but SocratiCode is not currently published there. Plugins are supported in the ChatGPT desktop Codex environment and Codex CLI. The Codex IDE extension supports shared MCP configuration, not plugin discovery. See the OpenAI plugin documentation.

Codex currently exposes enablement and tool policy for a plugin's bundled MCP server, but not a documented per-user environment override for that bundled definition. To keep the plugin skills while using custom SocratiCode variables, disable only the bundled server and add one top-level server in ~/.codex/config.toml:

[plugins."socraticode@socraticode".mcp_servers.socraticode]
enabled = false

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

[mcp_servers.socraticode.env]
QDRANT_MODE = "external"
QDRANT_URL = "https://xyz.qdrant.io"

Restart Codex, confirm that the plugin skills remain available, and use /mcp or codex mcp list to verify that exactly one SocratiCode server is active. See bundled MCP server policy and the Codex configuration reference.

OpenAI Codex MCP-only installation

codex mcp add writes the user configuration in ~/.codex/config.toml:

codex mcp add socraticode -- npx -y --prefer-online socraticode@latest
codex mcp list

Start a new task or CLI session after installation. The equivalent TOML is:

[mcp_servers.socraticode]
command = "npx"
args = ["-y", "--prefer-online", "socraticode@latest"]

Both inline env = { ... } and a nested [mcp_servers.socraticode.env] table are valid. The CLI --env KEY=value option is usually clearer. See the OpenAI Codex MCP documentation.

VS Code Agent Plugin

This plugin bundles the MCP server, skills, and agent instructions for VS Code's native agent. It is separate from the SocratiCode editor extension.

1. Add this complete setting to the current VS Code profile before installation:

   {
     "chat.plugins.enabled": true
   }
   

2. Run Chat: Install Plugin From Source from the Command Palette and enter https://github.com/giancarloerra/socraticode.

3. Start a new Chat session.

4. Verify SocratiCode under Agent Plugins - Installed, then run MCP: List Servers and confirm that its server is running.

Run Extensions: Check for Extension Updates to refresh installed agent plugins, then start a new Chat session. See VS Code Agent Plugins.

VS Code does not document a per-user environment overlay for a plugin-bundled MCP definition. To keep the plugin skills while applying custom variables, run MCP: List Servers, disable the bundled SocratiCode server, and add this user-scoped direct server through MCP: Open User Configuration:

{
  "servers": {
    "socraticode-configured": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--prefer-online", "socraticode@latest"],
      "env": {
        "QDRANT_MODE": "external",
        "QDRANT_URL": "https://xyz.qdrant.io"
      }
    }
  }
}

Start a new Chat and use MCP: List Servers to confirm that only socraticode-configured is active. Use envFile instead of env when variables should come from a separate local file. Server enablement is stored separately from the shared plugin definition. See VS Code MCP server management and the env / envFile reference.

VS Code editor extension

The separately published editor extension adds the SocratiCode sidebar, status item, commands, walkthrough, and interactive graph webview. Install SocratiCode from the Visual Studio Marketplace in the current VS Code profile.

On Microsoft VS Code 1.99+ and compatible editors that implement the VS Code MCP provider API, the extension registers SocratiCode with the editor's native MCP registry. It does not configure independent clients such as Cline, Continue, or Roo Code.

Reload the window and start a new Chat session after installation. Run MCP: List Servers to confirm that SocratiCode is running, and open the SocratiCode sidebar to verify the editor UI. Update it through the Extensions view or Extensions: Check for Extension Updates.

The Open VSX package can be installed in VS Code-derived editors, but native MCP registration requires that editor to implement vscode.lm.registerMcpServerDefinitionProvider. See the VS Code MCP extension API.

VS Code direct MCP installation