Summary
Brings local codebase intelligence to Claude through hybrid semantic and BM25 search, AST-aware dependency graphs, and symbol-level impact analysis across 18 languages. Runs entirely in Docker with Qdrant, indexing projects up to 40M+ lines with automatic file watching and resumable checkpoints. Exposes tools for querying code structure, tracing call flows, and analyzing blast radius without leaving your machine. Particularly strong on multi-repo setups where you need cross-project search or want to visualize circular dependencies. The indexer automatically picks up database schemas, API specs, and infra configs as searchable artifacts. If you're tired of grep or want smaller models to handle architectural questions, this gives them the precomputed context to do it.
Install to Claude Code
verifiedclaude mcp add socraticode --env EMBEDDING_PROVIDER=YOUR_EMBEDDING_PROVIDER --env OPENAI_API_KEY=YOUR_OPENAI_API_KEY --env GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY --env OLLAMA_URL=YOUR_OLLAMA_URL --env EMBEDDING_MODEL=YOUR_EMBEDDING_MODEL --env QDRANT_MODE=YOUR_QDRANT_MODE --env QDRANT_URL=YOUR_QDRANT_URL --env QDRANT_API_KEY=YOUR_QDRANT_API_KEY -- npx -y socraticodeRun in your terminal. Replace YOUR_* placeholders with real values; add --scope user to install for every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →
Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Tools
Verified live against the running server on Jun 10, 2026.
verified live25 tools
codebase_indexStart indexing a codebase in the background. Returns immediately. Call codebase_status to poll progress until 100%. Do NOT search until indexing is complete. If already indexing, returns current progress.2 params
Start indexing a codebase in the background. Returns immediately. Call codebase_status to poll progress until 100%. Do NOT search until indexing is complete. If already indexing, returns current progress.
Parameters* required
extraExtensionsstringComma-separated list of additional file extensions to index beyond the built-in set (e.g. '.tpl,.blade,.hbs'). Useful for projects with non-standard file extensions. Can also be set globally via EX...
projectPathstringAbsolute path to the project directory. If omitted, uses the current working directory.
codebase_updateIncrementally update an existing codebase index. Only re-indexes changed files. Runs synchronously. Usually not needed if file watcher is active.2 params
Incrementally update an existing codebase index. Only re-indexes changed files. Runs synchronously. Usually not needed if file watcher is active.
Parameters* required
extraExtensionsstringComma-separated list of additional file extensions to index (e.g. '.tpl,.blade').
projectPathstringAbsolute path to the project directory.
codebase_removeRemove a project's codebase index entirely from the vector database. Safely stops the file watcher, cancels any in-progress indexing/update (with drain), and waits for any in-flight graph build before deleting.1 params
Remove a project's codebase index entirely from the vector database. Safely stops the file watcher, cancels any in-progress indexing/update (with drain), and waits for any in-flight graph build before deleting.
Parameters* required
projectPath*stringAbsolute path to the project directory.
codebase_stopGracefully stop an in-progress indexing operation. The current batch will finish and checkpoint, preserving all progress. Re-run codebase_index to resume from where it left off.1 params
Gracefully stop an in-progress indexing operation. The current batch will finish and checkpoint, preserving all progress. Re-run codebase_index to resume from where it left off.
Parameters* required
projectPathstringAbsolute path to the project directory. If omitted, uses the current working directory.
codebase_watchStart/stop watching a project directory for file changes and automatically update the index. When starting, first runs an incremental update to catch any changes made since the last session, then keeps the index up to date via debounced file system watching.2 params
Start/stop watching a project directory for file changes and automatically update the index. When starting, first runs an incremental update to catch any changes made since the last session, then keeps the index up to date via debounced file system watching.
Parameters* required
action*stringstart/stop watching, or get status of watchers.one of
start · stop · statusprojectPathstringAbsolute path to the project directory.
codebase_searchSemantic search across an indexed codebase. Only use after codebase_index is complete (check codebase_status first). Returns relevant code chunks matching a natural language query.7 params
Semantic search across an indexed codebase. Only use after codebase_index is complete (check codebase_status first). Returns relevant code chunks matching a natural language query.
Parameters* required
fileFilterstringFilter results to a specific file path (relative).
includeLinkedbooleanWhen true, also search across linked projects defined in .socraticode.json or SOCRATICODE_LINKED_PROJECTS env var. Results include a project label showing which project each result came from. Defau...
languageFilterstringFilter results to a specific language (e.g. 'typescript', 'python').
limitnumberMaximum number of results to return. Default: 10 (override globally via SEARCH_DEFAULT_LIMIT env var).
minScorenumberMinimum RRF score threshold (0-1). Results below this are filtered out. Default: 0.10 (override globally via SEARCH_MIN_SCORE env var). Set to 0 to disable filtering.
projectPathstringAbsolute path to the project directory.
query*stringNatural language search query (e.g. 'authentication middleware', 'database connection setup').
codebase_statusCheck index status: chunk count, indexing progress (%), last completed operation, file watcher state. Call after codebase_index to poll until 100% complete.1 params
Check index status: chunk count, indexing progress (%), last completed operation, file watcher state. Call after codebase_index to poll until 100% complete.
Parameters* required
projectPathstringAbsolute path to the project directory.
codebase_graph_buildBuild a dependency graph of the codebase using static analysis (ast-grep). Maps import/require/export relationships between files. Runs in the background — call codebase_graph_status to poll progress until complete.2 params
Build a dependency graph of the codebase using static analysis (ast-grep). Maps import/require/export relationships between files. Runs in the background — call codebase_graph_status to poll progress until complete.
Parameters* required
extraExtensionsstringComma-separated list of additional file extensions to include in the graph (e.g. '.tpl,.blade'). Files with non-standard extensions are included as leaf nodes (dependency targets). Can also be set...
projectPathstringAbsolute path to the project directory.
codebase_graph_queryQuery the code dependency graph for a specific file. Returns what the file imports and what files depend on it.2 params
Query the code dependency graph for a specific file. Returns what the file imports and what files depend on it.
Parameters* required
filePath*stringRelative path of the file to query (e.g. 'src/index.ts').
projectPathstringAbsolute path to the project directory.
codebase_graph_statsGet statistics about the code dependency graph: total files, edges, most connected files, orphan files, circular dependencies.1 params
Get statistics about the code dependency graph: total files, edges, most connected files, orphan files, circular dependencies.
Parameters* required
projectPathstringAbsolute path to the project directory.
codebase_graph_circularFind circular dependencies in the codebase.1 params
Find circular dependencies in the codebase.
Parameters* required
projectPathstringAbsolute path to the project directory.
codebase_graph_visualizeVisualise the code dependency graph. Two modes: • mode="mermaid" (default) — returns a Mermaid diagram (text) colour-coded by language, circular deps highlighted. Best for inline rendering inside chat, GitHub, or editors that render Mermaid. • mode="interactive" — writes a sel...3 params
Visualise the code dependency graph. Two modes: • mode="mermaid" (default) — returns a Mermaid diagram (text) colour-coded by language, circular deps highlighted. Best for inline rendering inside chat, GitHub, or editors that render Mermaid. • mode="interactive" — writes a sel...
Parameters* required
modestring"mermaid" (default — text diagram) or "interactive" (browser-based explorer).one of
mermaid · interactiveopenbooleanIn interactive mode, whether to auto-open the browser. Default true. Set false to just get the file path (useful in headless environments).
projectPathstringAbsolute path to the project directory.
codebase_graph_removeRemove a project's persisted code graph. Waits for any in-flight graph build to finish first. The graph can be rebuilt with codebase_graph_build or will be rebuilt automatically on the next codebase_index.1 params
Remove a project's persisted code graph. Waits for any in-flight graph build to finish first. The graph can be rebuilt with codebase_graph_build or will be rebuilt automatically on the next codebase_index.
Parameters* required
projectPath*stringAbsolute path to the project directory.
codebase_graph_statusCheck the status of the code dependency graph: build progress (if building), node/edge count, when it was last built, whether it's cached in memory. Use this to poll progress after calling codebase_graph_build.1 params
Check the status of the code dependency graph: build progress (if building), node/edge count, when it was last built, whether it's cached in memory. Use this to poll progress after calling codebase_graph_build.
Parameters* required
projectPathstringAbsolute path to the project directory.
codebase_impactImpact Analysis — return the BLAST RADIUS for a file or symbol. Lists every file (and, where helpful, function) that could break if you change the target. Polymorphic on target: a path-like string ('src/foo.ts') triggers file-mode; a name-like string ('validateUser') triggers...3 params
Impact Analysis — return the BLAST RADIUS for a file or symbol. Lists every file (and, where helpful, function) that could break if you change the target. Polymorphic on target: a path-like string ('src/foo.ts') triggers file-mode; a name-like string ('validateUser') triggers...
Parameters* required
depthnumberHow many hops back to walk (default 3, max 10).
projectPathstringAbsolute path to the project directory.
target*stringTarget file path (relative) OR symbol name.
codebase_flowTrace the EXECUTION FLOW forward from an entry point — what does this code call into? With NO args, returns a ranked list of auto-detected entry points (orphans with outgoing calls, conventional names like main(), framework routes, tests). With an entrypoint argument, returns...4 params
Trace the EXECUTION FLOW forward from an entry point — what does this code call into? With NO args, returns a ranked list of auto-detected entry points (orphans with outgoing calls, conventional names like main(), framework routes, tests). With an entrypoint argument, returns...
Parameters* required
depthnumberMaximum DFS depth (default 5, max 10).
entrypointstringSymbol name to trace from. Omit to list auto-detected entry points.
filestringOptional file hint to disambiguate the symbol.
projectPathstringAbsolute path to the project directory.
codebase_symbol360° view of a symbol: definition, kind, callers, callees, confidence levels. Use to understand a function or class before changing it.3 params
360° view of a symbol: definition, kind, callers, callees, confidence levels. Use to understand a function or class before changing it.
Parameters* required
filestringOptional file hint to disambiguate when the name is not unique.
name*stringSymbol name (e.g. 'validateUser').
projectPathstringAbsolute path to the project directory.
codebase_symbolsList symbols in a file, or search by name across the project. Use to discover what exists before drilling into a single symbol with codebase_symbol.4 params
List symbols in a file, or search by name across the project. Use to discover what exists before drilling into a single symbol with codebase_symbol.
Parameters* required
filestringRelative file path — list all symbols in this file.
limitnumberMaximum results (default 200).
projectPathstringAbsolute path to the project directory.
querystringSubstring to match against symbol names project-wide.
codebase_contextList all context artifacts defined in .socraticodecontextartifacts.json — database schemas, API specs, infra configs, architecture docs, etc. Shows each artifact's name, description, path, and index status. Use this to discover what project knowledge is available beyond source...1 params
List all context artifacts defined in .socraticodecontextartifacts.json — database schemas, API specs, infra configs, architecture docs, etc. Shows each artifact's name, description, path, and index status. Use this to discover what project knowledge is available beyond source...
Parameters* required
projectPathstringAbsolute path to the project directory. If omitted, uses the current working directory.
codebase_context_searchSemantic search across context artifacts (database schemas, API specs, infra configs, etc.) defined in .socraticodecontextartifacts.json. Auto-indexes on first use and auto-detects stale artifacts. Use this to find relevant infrastructure or domain knowledge.5 params
Semantic search across context artifacts (database schemas, API specs, infra configs, etc.) defined in .socraticodecontextartifacts.json. Auto-indexes on first use and auto-detects stale artifacts. Use this to find relevant infrastructure or domain knowledge.
Parameters* required
artifactNamestringFilter search to a specific artifact by name (e.g. 'database-schema'). Omit to search across all artifacts.
limitnumberMaximum number of results to return. Default: 10.
minScorenumberMinimum RRF score threshold (0-1). Results below this are filtered out. Default: 0.10 (override globally via SEARCH_MIN_SCORE env var). Set to 0 to disable filtering.
projectPathstringAbsolute path to the project directory.
query*stringNatural language search query (e.g. 'tables related to billing', 'authentication endpoints', 'deployment resource limits').
codebase_context_indexIndex or re-index all context artifacts defined in .socraticodecontextartifacts.json. Chunks and embeds artifact content into the vector database for semantic search. Usually not needed — codebase_context_search auto-indexes on first use.1 params
Index or re-index all context artifacts defined in .socraticodecontextartifacts.json. Chunks and embeds artifact content into the vector database for semantic search. Usually not needed — codebase_context_search auto-indexes on first use.
Parameters* required
projectPathstringAbsolute path to the project directory.
codebase_context_removeRemove all indexed context artifacts for a project from the vector database. Blocked while indexing is in progress — use codebase_stop or wait for the operation to finish first.1 params
Remove all indexed context artifacts for a project from the vector database. Blocked while indexing is in progress — use codebase_stop or wait for the operation to finish first.
Parameters* required
projectPath*stringAbsolute path to the project directory.
codebase_healthCheck the health of all infrastructure: Docker, Qdrant container, Ollama, and embedding model. Use this to diagnose setup issues.
Check the health of all infrastructure: Docker, Qdrant container, Ollama, and embedding model. Use this to diagnose setup issues.
No parameters — call it with no arguments.
codebase_list_projectsList all projects that have been indexed (have collections in Qdrant).
List all projects that have been indexed (have collections in Qdrant).
No parameters — call it with no arguments.
codebase_aboutDisplay information about SocratiCode — what it is, its tools and how to use it. Use this to get a quick overview of the MCP tools and their purpose.
Display information about SocratiCode — what it is, its tools and how to use it. Use this to get a quick overview of the MCP tools and their purpose.
No parameters — call it with no arguments.
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.
Kindly sponsored by Altaire Limited
🛡️ 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
- Quick guides
- 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
npxonPATH, plus Docker running for the default local Qdrant and Ollama stack.
For one recommended setup path per host and short practical scenarios, use the quick guides. This README has the other installation paths and full configuration.
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, and Cline 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 direct MCP | Restart Gemini to reconnect the server and resolve the current npm release |
| 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.
Prefer updates at Git transitions? Set SOCRATICODE_WATCHER=git. Active indexed checkouts refresh when the checked-out ref or HEAD changes, without a native file watcher. See Git-triggered refresh.
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 separateclaude 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, or a directly configured local stdio MCP server. These are separate integration types and use different configuration and update paths.
The SocratiCode engine requires Node.js 18.17 or newer with npx on PATH; some hosts require a newer Node.js version. 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 | Direct MCP | User |
| Continue | Direct MCP | Project or user config |
| Cline | 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.
Pinning the engine version
By default the plugin launches npx -y --prefer-online socraticode@latest, which checks npm for the current release every time the server starts. Each start resolves independently, so two servers begun at different moments on one host can run different releases.
SOCRATICODE_SPEC replaces the package specification. Unset, it resolves to socraticode@latest and the launcher is unchanged, so an existing installation needs no reconfiguration. Set it where the plugin's server inherits it, in Claude Code's user settings:
{
"env": {
"SOCRATICODE_SPEC": "socraticode@1.14.0"
}
}
Remove the entry to go back to the default; an empty string is a value, not an absence, and would be passed to npm as the specification.
Every server on that host then resolves the same build. npm is still contacted for metadata, so start-up is not free, but a pinned version is already in the npx cache after its first resolution and is not downloaded again on each new release. A pinned engine no longer updates on its own — raise the value deliberately to pick up a release.
This applies to the Claude Code plugin only. Codex and Cursor read the shared .mcp.json, whose launcher is unchanged; the VS Code extension exposes the equivalent socraticode.command and socraticode.args settings.
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
If SocratiCode fails to start in Codex Desktop with No such file or directory, Codex may not be able to find npx. Run command -v npx. Some desktop launches use only /usr/bin:/bin:/usr/sbin:/sbin; if npx is installed elsewhere, add its directory to PATH in the custom Codex configuration below, then restart Codex.
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.
-
Add this complete setting to the current VS Code profile before installation:
{ "chat.plugins.enabled": true } -
Run Chat: Install Plugin From Source from the Command Palette and enter
https://github.com/giancarloerra/socraticode. -
Start a new Chat session.
-
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 or Continue.
Enable VS Code's AI features and sign in to GitHub Copilot for native Agent Chat. On VS Code 1.122+, a BYOK model with tool calling also works without GitHub sign-in. 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
Use the Stable or Insiders badge above, choose user or workspace scope in VS Code, then start a new Chat session. A project-scoped .vscode/mcp.json uses this complete object:
{
"servers": {
"socraticode": {
"type": "stdio",
"command": "npx",
"args": ["-y", "--prefer-online", "socraticode@latest"]
}
}
}
Verify with MCP: List Servers. Restart the server from that command and start a new Chat session after a release.
Cursor
The repository includes a Cursor-format plugin with the MCP server, skills, and instructions. SocratiCode is not currently published in the Cursor Marketplace, so use Cursor's documented user-scoped local-plugin directory. Clone the repository, then check out the stable version shown on the latest SocratiCode release:
mkdir -p ~/.cursor/plugins/local
git clone https://github.com/giancarloerra/socraticode.git ~/.cursor/plugins/local/socraticode
git -C ~/.cursor/plugins/local/socraticode checkout <latest-release-tag>
Replace <latest-release-tag> with the release tag shown on that page, for example vX.Y.Z. Restart Cursor or run Developer: Reload Window, then verify the plugin under Customize. To update to a later public release:
git -C ~/.cursor/plugins/local/socraticode fetch --tags
git -C ~/.cursor/plugins/local/socraticode checkout <latest-release-tag>
Reload Cursor after updating. These commands intentionally follow release tags rather than unreleased commits on main. See Cursor plugins.
For direct MCP configuration, use the Cursor badge above and select the intended user or project scope in Cursor. Start a new Agent chat, then verify socraticode under Customize → MCPs. The installation link already uses the latest-release engine command. See Cursor MCP install links.
The current local plugin does not declare user-configurable variables. To keep its skills while applying custom variables, open Customize, disable the plugin-provided SocratiCode MCP server, and add one direct server to the user or project mcp.json:
{
"mcpServers": {
"socraticode-configured": {
"command": "npx",
"args": ["-y", "--prefer-online", "socraticode@latest"],
"env": {
"QDRANT_MODE": "external",
"QDRANT_URL": "https://xyz.qdrant.io"
}
}
}
}
Reload Cursor and verify under Customize that only socraticode-configured is active. See Cursor plugin variables and MCP server management.
The SocratiCode package on Open VSX is a VS Code-style editor extension, not a Cursor plugin. Installing that extension does not establish that Cursor implements VS Code's native MCP provider API. Use the local plugin or direct MCP path when MCP availability is required.
Gemini CLI
Add the user-scoped MCP server, verify it, then restart any active Gemini CLI session:
gemini mcp add --scope user socraticode npx -y --prefer-online socraticode@latest
gemini mcp list
For advanced configuration, edit the server in user scope (~/.gemini/settings.json) or define it in workspace scope (.gemini/settings.json) and explicitly forward the variables named in env:
{
"mcpServers": {
"socraticode": {
"command": "npx",
"args": ["-y", "--prefer-online", "socraticode@latest"],
"env": {
"EMBEDDING_PROVIDER": "openai",
"OPENAI_API_KEY": "${OPENAI_API_KEY}",
"QDRANT_MODE": "external",
"QDRANT_URL": "${QDRANT_URL}",
"QDRANT_API_KEY": "${QDRANT_API_KEY}"
}
}
}
}
Keep secret values in the process environment rather than committing them. Restart Gemini and run gemini mcp list to verify the configured server. See Gemini MCP configuration.
Continue
Continue uses a YAML mcpServers list. For project scope, create .continue/mcpServers/socraticode.yaml:
name: SocratiCode MCP
version: 1.0.0
schema: v1
mcpServers:
- name: SocratiCode
type: stdio
command: npx
args:
- "-y"
- "--prefer-online"
- socraticode@latest
Continue refreshes saved configuration automatically. Open a new Continue Agent session and confirm the SocratiCode tools are listed. For user scope, add the same mcpServers list to ~/.continue/config.yaml. Continue can also import complete JSON MCP files placed in .continue/mcpServers/. See Continue MCP configuration and the Continue YAML reference.
Cline
For project scope, save this complete object as .cline/mcp.json. For user scope, add the same server to ~/.cline/data/settings/cline_mcp_settings.json through Cline's MCP settings interface:
{
"mcpServers": {
"socraticode": {
"command": "npx",
"args": ["-y", "--prefer-online", "socraticode@latest"],
"disabled": false,
"autoApprove": []
}
}
}
Start a new Cline task and verify that socraticode and its tools appear in the MCP Servers view. Reconnect the server after a release. See the Cline MCP documentation.
Zed
Open Settings → AI → MCP Servers → Add Server → Add Local Server. The UI writes user-scoped settings. Use this complete server definition, either there or in project-scoped .zed/settings.json:
{
"context_servers": {
"socraticode": {
"command": "npx",
"args": ["-y", "--prefer-online", "socraticode@latest"],
"env": {}
}
}
}
Verify that the indicator beside SocratiCode is green and its tooltip says Server is active, then start a new Agent conversation. Restart the server from the MCP Servers page after a release.
Zed uses ~/.config/zed/AGENTS.md for personal instructions. For project instructions it uses the first matching supported file, which can be AGENTS.md, CLAUDE.md, GEMINI.md, or another supported compatibility file. Zed Rules were replaced by Skills and Instructions. See Zed MCP servers and Zed Instructions.
OpenCode
Use project-root opencode.json or opencode.jsonc for project scope. Use ~/.config/opencode/opencode.json or opencode.jsonc for user scope:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"socraticode": {
"type": "local",
"command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
"enabled": true
}
}
}
Restart OpenCode and verify the server with opencode mcp list. Restart OpenCode after a release so npm can check for the current engine. This is the OpenCode 1.x schema.
OpenCode V2 nests server names under mcp.servers and uses disabled instead of enabled; its local server definition is otherwise equivalent:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"socraticode": {
"type": "local",
"command": ["npx", "-y", "--prefer-online", "socraticode@latest"],
"disabled": false,
"environment": {}
}
}
}
}
See OpenCode 1.x MCP servers, OpenCode V2 MCP servers, and OpenCode configuration.
Other local stdio MCP hosts
The complete JSON object in Quick Start applies only to hosts whose documentation specifies an mcpServers object. Add it at the user or project scope documented by that host, restart the MCP server or start a new session, and verify SocratiCode in the host's MCP server and tool list. The example already checks for the latest published engine whenever the server starts. Hosts that support only remote HTTP MCP servers cannot launch SocratiCode directly.
Why SocratiCode
I built SocratiCode because I regularly work on existing, large, and complex codebases across different languages and need to quickly understand them and act. Existing solutions were either too limited, insufficiently tested for production use, or bloated with unnecessary complexity. I wanted a single focused tool that does deep codebase intelligence well — zero setup, no bloat, fully automatic — and gets out of the way.
Built-in Code Search vs SocratiCode
| Feature | Claude Code | Cursor | VS Code Copilot | + SocratiCode |
|---|---|---|---|---|
| Text / grep search | ✅ | ✅ | ✅ | ✅ |
| Semantic search | — | ✅ | ✅¹ | ✅ |
| Hybrid search (fused) | — | — | — | ✅ |
| Code dependency graph | — | — | ✅² | ✅ |
| Symbol-level impact / blast radius | — | — | — | ✅ |
| Call-flow tracing (entry point → callees) | — | — | — | ✅ |
| Interactive visual graph explorer | — | — | — | ✅ |
| Circular dependency detection | — | — | — | ✅ |
| Non-code knowledge (schemas, API specs) | — | — | — | ✅ |
| Cross-project search | — | — | — | ✅ |
| Branch-aware indexing | — | — | — | ✅ |
| Multi-agent shared index | — | — | — | ✅ |
| Tool-independent (survives switching AI) | — | — | — | ✅ |
| Fully local / private | ✅ | —³ | —⁴ | ✅ |
| Resumable indexing | — | — | — | ✅ |
| Live file watching | — | ✅ | — | ✅ |
¹ VS Code Copilot: remote index via GitHub / Azure DevOps; local "External Ingest" gradually rolling out. ² LSP-based Find References / Go to Definition (Usages tool), not a full dependency graph. ³ Cursor: embeddings processed on Cursor servers (encrypted in transit and at rest). ⁴ VS Code Copilot: remote index hosted on GitHub / Azure DevOps. Sources: Cursor docs, Claude Code docs, VS Code Copilot docs.
🔌 The context lives with your codebase, not with the assistant. Built-in indexes (Cursor's, Copilot's) are tied to that one tool — switch assistants and you start from scratch. SocratiCode is independent: index once, then plug it into Claude Code, Cursor, Copilot, Windsurf, your own private model, or all of them at once. They share the same understanding of your code.
On VS Code's 2.45M‑line codebase, SocratiCode answers architectural questions with 61% less data, 84% fewer steps, and 37× faster response than a grep‑based AI agent. Full benchmark →
Features
- Hybrid code search — Built on Qdrant, a purpose-built vector database with HNSW indexing, concurrent read/write, and payload filtering. Each chunk stores both a dense vector and a BM25 sparse vector; the Query API runs both sub-queries in a single round-trip and fuses results with Reciprocal Rank Fusion (RRF). Semantic search handles conceptual queries like "authentication middleware" even when those exact words don't appear in the code. BM25 handles exact identifier and keyword lookups. You get the best of both in every query with no tuning required.
- Configurable Qdrant — Use the built-in Docker Qdrant (default, zero config) or connect to your own instance (self-hosted, remote server, or Qdrant Cloud). Configure via
QDRANT_MODE,QDRANT_URL, andQDRANT_API_KEYenvironment variables. - Configurable Ollama — Use the built-in Docker Ollama (default, zero config) or point to your own Ollama instance (native install -GPU access-, remote server, etc.). Configure via
OLLAMA_MODE,OLLAMA_URL,EMBEDDING_MODELandEMBEDDING_DIMENSIONSenvironment variables. - Multi-provider embeddings — Switch between Local Ollama (private, GPU access), Docker Ollama (zero-config), OpenAI (
text-embedding-3-small, fastest), Google Gemini (gemini-embedding-001, free tier), LM Studio (local OpenAI-compatible server), or LiteLLM (proxy gateway in front of 100+ providers) with a single environment variable. No provider-specific configuration files. - Private & secure — Everything runs on your machine — your code never leaves your network. The default Docker setup includes Ollama (embeddings) and Qdrant (vector storage) with no external API calls. No API costs, no token limits. Suitable for air-gapped and on-premises environments. Optional cloud providers (OpenAI, Google Gemini, Qdrant Cloud) are available but never required.
- AST-aware chunking — Files are split at function/class boundaries using AST parsing (ast-grep), not arbitrary line counts. This produces higher-quality search results. Falls back to line-based chunking for unsupported languages.
- Polyglot code dependency graph — Static analysis of import/require/use/include statements using ast-grep for 19+ languages. No external tools like dependency-cruiser required. Detects circular dependencies and generates visual Mermaid diagrams.
- Broad language support — Works with every supported file type out of the box. Fully supported languages bundle their grammars. GDScript uses an optional native parser when compatible and a syntax-aware fallback otherwise. For non-standard extensions, configure
EXTRA_EXTENSIONS. If your AI can read it, SocratiCode can index it. - Incremental indexing — After the first full index, only changed files are re-processed. Content hashes are persisted in Qdrant so state survives server restarts.
- Batched & resumable indexing — Files are processed in batches of 50, with progress checkpointed to Qdrant after each batch. If the process crashes or is interrupted, the next run automatically resumes from where it left off — already-indexed files are skipped via hash comparison. This keeps peak memory low and makes indexing reliable even for very large codebases.
- Live file watching — Optionally watch for file changes and keep the index updated in real time (debounced 2s). Watcher also invalidates the code graph cache.
- Parallel processing — Files are scanned and chunked in parallel batches (50 at a time) for fast I/O, while embedding generation and upserts are batched separately for optimal throughput.
- Multi-project — Index multiple projects simultaneously. Each gets its own isolated collection with full project path tracking.
- Cross-project search — Search across multiple related projects in a single query. Link projects via
.socraticode.jsonor theSOCRATICODE_LINKED_PROJECTSenv var, then setincludeLinked: trueoncodebase_search. Results are tagged with project labels and ranked by cosine similarity, which is comparable across projects of very different sizes (falling back to rank fusion when a cosine is unavailable for any hit). - Branch-aware indexing — Maintain separate indexes per git branch by setting
SOCRATICODE_BRANCH_AWARE=true. Each branch gets its own Qdrant collections, so switching branches instantly switches to the correct index. Ideal for CI/CD pipelines and PR review workflows. Requires a path-derived project id: an explicit id (SOCRATICODE_PROJECT_ID, orprojectIdin.socraticode.json) is treated as a stable identity and is never suffixed, so branch-aware mode does not apply to those projects. - Respects ignore rules — Honors all
.gitignorefiles (root + nested), plus an optional.socraticodeignorefor additional exclusions. Includes sensible built-in defaults..gitignoreprocessing can be disabled viaRESPECT_GITIGNORE=false. Dot-directories (e.g..agent) can be included viaINCLUDE_DOT_FILES=true. - Custom file extensions — Projects with non-standard extensions (e.g.
.tpl,.blade) can be included viaEXTRA_EXTENSIONSenv var orextraExtensionstool parameter. Such files are indexed as plaintext and appear as leaf nodes in the code graph (no AST chunking or symbols). To instead treat a custom extension as a real language (full AST chunking, symbols, call graph), map it withEXTENSION_LANGUAGE_MAP(e.g..inc:php). - Configurable infrastructure — All ports, hosts, and API keys are configurable via environment variables. Qdrant API key support for enterprise deployments.
- Enterprise-ready simplicity — No agent coordination tuning, no memory limit environment variables, no coordinator/conductor capacity knobs, no backpressure configuration. SocratiCode scales by relying on production-grade infrastructure (Qdrant, proven embedding APIs) rather than complex in-process orchestration.
- Auto-setup & zero configuration — Just install the Claude Plugin/Skill or add the MCP server to your AI host config. On first use, the server automatically checks Docker, pulls images, starts Qdrant and Ollama containers, and downloads the embedding model. No config files, YAML, environment variables, or required native compilation. The optional GDScript parser falls back safely when no compatible native build is available. Works everywhere Docker runs.
- Session resume — By default, server startup resumes the indexed project represented by the MCP process's working directory. Complete indexes get a watcher plus an incremental catch-up update; interrupted indexes resume from the last checkpoint. Explicit project lists and
SOCRATICODE_AUTO_RESUME=allextend this to other indexed projects. - Auto-start watcher — In the default
SOCRATICODE_WATCHER=automode, the file watcher starts during startup resume and aftercodebase_indexorcodebase_update. A completed indexed project not selected at startup gets a fallback watcher start on its first search, status, or graph interaction.manualpermits only an explicitcodebase_watch { action: "start" };offdisables watcher startup completely. - Manual index snapshots —
SOCRATICODE_WATCHER=offplusSOCRATICODE_AUTO_RESUME=offprevents implicit code-index updates, embeddings, and graph creation. Existing code indexes and graphs stay readable; refresh them explicitly withcodebase_index,codebase_update, orcodebase_graph_build. - Git-triggered refresh:
SOCRATICODE_WATCHER=gitchecks active indexed checkouts every 10 seconds and on search, status, and graph requests. A checked-out ref or HEAD change triggers the existing incremental updater and graph reconciliation. Native file watching stays disabled, including explicit watcher starts. - Auto-build code graph — The code dependency graph is automatically built after indexing and rebuilt when watched files change. An update that changed nothing the graph is built from — a README, a fixture, a migration — reuses the existing graph rather than rebuilding it; each build records the inputs it read, and the rebuild is skipped only when every one of them is unchanged. Any graph-relevant addition rebuilds — a file appearing where the build looked, but not one the ignore rules exclude — and so does any configuration change, or a graph with no such record. No need to call
codebase_graph_buildmanually unless you want to force a rebuild. - Multi-agent collaboration — Multiple AI agents (each running their own MCP instance) can work on the same codebase simultaneously and share a single index. One agent triggers indexing, all agents search against the same data. Only one watcher runs per project — every agent benefits from real-time updates. Cross-process file locking coordinates indexing and watching automatically. Ideal for workflows like one agent writing tests while another fixes code, or a planning agent and an implementation agent working in parallel.
- Cross-process safety — File-based locking (
proper-lockfile) prevents multiple MCP instances from simultaneously indexing or watching the same project. Stale locks from crashed processes are automatically reclaimed. When another MCP process is already watching a project,codebase_statusreports "active (watched by another process)" instead of incorrectly showing "inactive." - Concurrency guards — Duplicate indexing and graph-build operations are prevented. If you call
codebase_indexwhile indexing is already running, it returns the current progress instead of starting a second operation. - Graceful stop — Long-running indexing operations can be stopped safely with
codebase_stop. The current batch finishes and checkpoints, preserving all progress. Re-runcodebase_indexto resume from where it left off. - Explicit reclamation —
codebase_prunelists what the store holds and deletes one identity at a time, only on an explicit, confirmed apply. See Reclaiming stored identities. - Graceful shutdown — On server shutdown, active indexing operations are given up to 60 seconds to complete, all file watchers are stopped cleanly, and the everything closes gracefully.
- Structured logging — All operations are logged with structured context for observability. Log level configurable via
SOCRATICODE_LOG_LEVEL. - Graceful degradation — If infrastructure goes down during watch, the watcher backs off and retries instead of crashing.
Prerequisites
| Dependency | Purpose | Install |
|---|---|---|
| Docker | Runs Qdrant (vector DB) and by default Ollama (embeddings) | docker.com |
Node.js 18.17+ with npx on PATH | Runs the MCP server | nodejs.org |
Docker must be running when you use the server in the default managed mode.
The Qdrant container is managed automatically. If you set QDRANT_MODE=external and point QDRANT_URL at a remote or cloud Qdrant instance, Docker is only needed for Ollama (embeddings) in that case.
The Ollama container (embeddings) is also managed automatically in the default auto mode. SocratiCode first checks if Ollama is already running natively — if so it uses it. Otherwise it manages a Docker container for you. First-time download of the docker images or embedding models may take a few minutes, depending on your internet speed, and is required only at first launch.
Embedding performance on macOS / Windows
Docker containers on macOS and Windows cannot access the GPU (no Metal or CUDA passthrough). For small projects this is fine, but for medium-to-large codebases the CPU-only container is noticeably slower.
For best performance, install native Ollama: download and run the installer from ollama.com/download. Once Ollama is running, SocratiCode will automatically detect and use it — no extra configuration needed (first-time download of the embedding model, if not present, might take a few minutes). This gives you Metal GPU acceleration on macOS and CUDA on Windows/Linux.
If you prefer speed without a local install, see OpenAI Embeddings and Google Generative AI Embeddings below for cloud-based options. OpenAI is very fast with no local setup required. Google’s free tier is functional but rate-limited. See Environment Variables for configuration details.
Example Workflow
All tools default projectPath to the current working directory, so you never need to specify a path for the active project.
User: "Index this project"
→ codebase_index {}
⚡ Indexing started in the background — call codebase_status to check progress
→ codebase_status {}
⚠ Full index in progress — Phase: generating embeddings (batch 1/1)
Progress: 247/1847 chunks embedded (13%) — Elapsed: 12s
→ codebase_status {}
✓ Indexing complete: 342 files, 1,847 chunks (took 115.2s)
File watcher: active (auto-updating on changes)
User: "Search for how authentication is handled"
→ codebase_search { query: "authentication handling" }
Runs dense semantic search + BM25 keyword search in parallel, fuses results with RRF
Returns top 10 results ranked by combined relevance
User: "What files depend on the auth middleware?"
→ codebase_graph_query { filePath: "src/middleware/auth.ts" }
Returns imports and dependents
(graph was auto-built after indexing — no manual build needed)
User: "Show me the dependency graph"
→ codebase_graph_visualize {}
Returns a Mermaid diagram colour-coded by language
User: "Are there any circular dependencies?"
→ codebase_graph_circular {}
Found 2 cycles: src/a.ts → src/b.ts → src/a.ts
User: "What breaks if I rename validateUser?"
→ codebase_impact { target: "validateUser" }
Blast radius for symbol: validateUser
Hop 1 (3 files): src/auth/login.ts, src/api/users.ts, tests/auth.test.ts
Hop 2 (5 files): ...
User: "What does the server entry point actually do?"
→ codebase_flow {}
Detected 4 entry point(s):
main (cmd/server.go:10) — well-known-name:main
healthz (src/api/routes.ts:42) — framework:get
...
→ codebase_flow { entrypoint: "main" }
└── main (cmd/server.go:10)
├── loadConfig (cmd/server.go:15)
└── startServer (src/server.ts:8)
└── ...
User: "Who calls bcryptCompare and what does it call?"
→ codebase_symbol { name: "bcryptCompare" }
Symbol: bcryptCompare (function)
Defined: src/auth/hash.ts:42–58
Callers (3): ← src/auth/login.ts:12, ← src/auth/reset.ts:30 ...
Callees (1): → compare [unique, 1 candidate]
Agent Instructions
Claude Code plugin users: These instructions are included automatically as skills in the SocratiCode plugin. You don't need to copy them into
CLAUDE.md. The section below is for non-Claude Code hosts (VS Code, Cursor, Claude Desktop, etc.).
For best results, add instructions like the following to your AI assistant's project-level instructions file. The core principle: search before reading. The index gives you a map of the codebase in milliseconds; raw file reading is expensive and context-consuming.
Where to place these instructions (per IDE):
| IDE / Tool | Instructions file |
|---|---|
| Claude Code | CLAUDE.md at project root (auto-loaded). Plugin users get this via skills automatically. |
| Cursor | AGENTS.md at project root, or .cursor/rules/socraticode.mdc for a dedicated rule file |
| VS Code Copilot | .github/copilot-instructions.md, or a custom instructions file in your VS Code User prompts folder |
| Zed | AGENTS.md at project root, or ~/.config/zed/AGENTS.md for personal instructions. Zed uses the first matching supported project instruction file. |
| Windsurf | .windsurfrules at project root |
| Claude Desktop / Cline | Add directly to your system prompt configuration |
Why this matters: Installing the MCP server alone gives your agent access to SocratiCode tools, but the agent still decides when to use them. Adding these instructions to your project ensures the agent consistently prefers SocratiCode search over raw file reads, uses the graph for dependency-aware tasks, and follows the search-before-reading workflow.
## Codebase Search (SocratiCode)
This project is indexed with SocratiCode. Always use its MCP tools to explore the codebase
before reading any files directly.
### Workflow
1. **Start most explorations with `codebase_search`.**
Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.
- Use broad, conceptual queries for orientation: "how is authentication handled",
"database connection setup", "error handling patterns".
- Use precise queries for symbol lookups: exact function names, constants, type names.
- Prefer search results to infer which files to read — do not speculatively open files.
- **When to use grep instead**: If you already know the exact identifier, error string,
or regex pattern, grep/ripgrep is faster and more precise — no semantic gap to bridge.
Use `codebase_search` when you're exploring, asking conceptual questions, or don't
know which files to look in.
2. **Follow the graph before following imports.**
Use `codebase_graph_query` to see what a file imports and what depends on it before
diving into its contents. This prevents unnecessary reading of transitive dependencies.
- **Before modifying or deleting a file**, check its dependents with `codebase_graph_query`
to understand the blast radius.
- **When planning a refactor**, use the graph to identify all affected files before
making changes.
3. **Use Impact Analysis BEFORE refactoring, renaming, or deleting code.**
The symbol-level call graph (`codebase_impact`, `codebase_flow`, `codebase_symbol`,
`codebase_symbols`) goes one step deeper than the file graph: it knows which
functions and methods call which.
- `codebase_impact` answers "what breaks if I change X?" (blast radius — every file
that transitively calls into the target).
- `codebase_flow` answers "what does this code do?" by tracing forward from an entry
point. Call with no `entrypoint` to discover candidate entry points (auto-detected
via orphans, conventional names like `main()`, framework routes, tests).
- `codebase_symbol` gives a 360° view of one function: definition, callers, callees.
- `codebase_symbols` lists symbols in a file or searches by name.
- Always prefer these over reading multiple files when the question is about
dependencies between functions, not concepts.
4. **Read files only after narrowing down via search.**
Once search results clearly point to 1–3 files, read only the relevant sections.
Never read a file just to find out if it's relevant — search first.
5. **Use `codebase_graph_circular` when debugging unexpected behaviour.**
Circular dependencies cause subtle runtime issues; check for them proactively.
Also run `codebase_graph_circular` when you notice import-related errors or unexpected
initialisation order.
6. **Check `codebase_status` if search returns no results.**
The project may not be indexed yet. Run `codebase_index` if needed, then wait for
`codebase_status` to confirm completion before searching.
7. **Leverage context artifacts for non-code knowledge.**
Projects can define a `.socraticodecontextartifacts.json` config to expose database
schemas, API specs, infrastructure configs, architecture docs, and other project
knowledge that lives outside source code. These artifacts are auto-indexed alongside
code during `codebase_index` and `codebase_update`.
- Run `codebase_context` early to see what artifacts are available.
- Use `codebase_context_search` to find specific schemas, endpoints, or configs
before asking about database structure or API contracts.
- If `codebase_status` shows artifacts are stale, run `codebase_context_index` to
refresh them.
### When to use each tool
| Goal | Tool |
|------|------|
| Understand what a codebase does / where a feature lives | `codebase_search` (broad query) |
| Find a specific function, constant, or type | `codebase_search` (exact name) or grep if you know already the exact string |
| Find exact error messages, log strings, or regex patterns | grep / ripgrep |
| See what a file imports or what depends on it | `codebase_graph_query` |
| Check blast radius before modifying or deleting a file | `codebase_impact` (symbol-level) or `codebase_graph_query` (file-level) |
| **What breaks if I change function X?** | `codebase_impact target=X` |
| **What does this entry point actually do?** | `codebase_flow entrypoint=X` |
| **List entry points in this codebase** | `codebase_flow` (no args) |
| **Who calls this function and what does it call?** | `codebase_symbol name=X` |
| **What functions/classes exist in this file?** | `codebase_symbols file=path` |
| **Search for symbols by name across the project** | `codebase_symbols query=X` |
| Spot architectural problems | `codebase_graph_circular`, `codebase_graph_stats` |
| Visualise module structure | `codebase_graph_visualize` |
| Verify index is up to date | `codebase_status` |
| Discover what project knowledge (schemas, specs, configs) is available | `codebase_context` |
| Find database tables, API endpoints, infra configs | `codebase_context_search` |
Why semantic search first? A single
codebase_searchcall returns ranked, deduplicated snippets from across the entire codebase in milliseconds. This gives you a broad map at negligible token cost — far cheaper than opening files speculatively. Once you know which files matter, targeted reading is both faster and more accurate. That said, grep remains the right tool when you have an exact string or pattern — use whichever fits the query.
Keep the connection alive during indexing. Indexing runs in the background — the MCP server continues working even when not actively responding to tool calls. However, some MCP hosts might disconnect an idle MCP connection after a period of inactivity, which might cut off the background process. Instruct your AI to call
codebase_statusroughly every 60 seconds after startingcodebase_indexuntil it completes. This keeps the host connection active and provides real-time progress.
Configuration
Install
Use the host-specific steps in Plugins and host integrations. They cover installation scope, activation, verification, updates, and each host's actual configuration schema.
From source (for contributors)
git clone https://github.com/giancarloerra/socraticode.git
cd socraticode
npm install
npm run build
Featured
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Configuration
EMBEDDING_PROVIDEREmbedding provider to use: ollama (default), openai, or google
OPENAI_API_KEYsecretAPI key for OpenAI embeddings (required only when EMBEDDING_PROVIDER=openai)
GOOGLE_API_KEYsecretAPI key for Google embeddings (required only when EMBEDDING_PROVIDER=google)
OLLAMA_URLURL of the Ollama server (default: auto-detected; Docker-managed or http://localhost:11434)
EMBEDDING_MODELEmbedding model name (defaults per provider: nomic-embed-text for ollama, text-embedding-3-small for openai, gemini-embedding-001 for google)
QDRANT_MODEQdrant mode: managed (default, Docker-managed) or external (user-provided instance)
QDRANT_URLFull URL for remote/cloud Qdrant (e.g. https://xyz.cloud.qdrant.io:6333). Only needed when QDRANT_MODE=external
QDRANT_API_KEYsecretAPI key for remote Qdrant instance. Only needed when QDRANT_MODE=external
Categories
Registryactive
Packagesocraticode
TransportSTDIO
AuthRequired
Tools verifiedJun 10, 2026
UpdatedMar 4, 2026
