giancarloerra · giancarloerra · Mar 15, 2026 · Mar 15, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -0,0 +1,16 @@
+{
+  "name": "socraticode",
+  "version": "1.0.1",
+  "description": "Codebase intelligence — semantic search workflows, dependency graph analysis, and context artifact exploration for SocratiCode",
+  "author": {
+    "name": "Giancarlo Erra",
+    "email": "giancarlo@altaire.com",
+    "url": "https://altaire.com"
+  },
+  "homepage": "https://github.com/giancarloerra/socraticode",
+  "repository": "https://github.com/giancarloerra/socraticode",
+  "license": "AGPL-3.0-only",
+  "keywords": ["codebase", "search", "indexing", "dependency-graph", "semantic-search", "mcp"],
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.json"
+}
diff --git a/.mcp.json b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "socraticode": {
+      "command": "npx",
+      "args": ["-y", "socraticode"]
+    }
+  }
+}
diff --git a/.release-it.json b/.release-it.json
@@ -1,4 +1,7 @@
 {
+  "hooks": {
+    "after:bump": "node -e \"const fs=require('fs'); const p=JSON.parse(fs.readFileSync('.claude-plugin/plugin.json','utf8')); p.version='${version}'; fs.writeFileSync('.claude-plugin/plugin.json', JSON.stringify(p,null,2)+'\\n');\""
+  },
   "git": {
     "commitMessage": "chore: release v${version}",
     "tagName": "v${version}",

diff --git a/README.md b/README.md
@@ -13,6 +13,7 @@
 </p>
 
 <p align="center">
+  <a href="#claude-code-plugin-recommended-for-claude-code-users"><img src="https://img.shields.io/badge/Claude_Code-Install_Plugin-CC785C?style=flat-square&logoColor=white" alt="Install Claude Code Plugin"></a>
   <a href="https://insiders.vscode.dev/redirect/mcp/install?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D"><img src="https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code"></a>
   <a href="https://insiders.vscode.dev/redirect/mcp/install?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders"><img src="https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code Insiders"></a>
   <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19"><img src="https://img.shields.io/badge/Cursor-Install_MCP_Server-F14C28?style=flat-square&logo=cursor&logoColor=white" alt="Install in Cursor"></a>
@@ -28,16 +29,26 @@
 
 > 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 and it manages everything automatically.
+**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 server 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.
+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 →](#real-world-benchmark-vs-code-245m-lines-of-code-with-claude-opus-46)
 
+<p align="center">
+<a href="https://www.star-history.com/?repos=giancarloerra%2Fsocraticode&type=date&logscale=&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=giancarloerra/socraticode&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=giancarloerra/socraticode&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=giancarloerra/socraticode&type=date&legend=top-left" />
+ </picture>
+</a>
+</p>
+
 ## Contents
 
 - [Quick Start](#quick-start)
@@ -63,9 +74,10 @@ The first Qdrant‑based MCP server that pairs auto‑managed, zero‑config loc
 
 > **Only [Docker](https://www.docker.com/products/docker-desktop/) (running) required.**
 
-**One-click install** — VS Code and Cursor:
+**One-click install** — Claude Code, VS Code and Cursor,:
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP_Server-F14C28?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19)
+[![Install Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Install_Plugin-CC785C?style=flat-square&logoColor=white)](#claude-code-plugin-recommended-for-claude-code-users)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=socraticode&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22socraticode%22%5D%7D&quality=insiders) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_MCP_Server-F14C28?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=socraticode&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNvY3JhdGljb2RlIl19) 
 
 **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:
 
@@ -76,7 +88,13 @@ The first Qdrant‑based MCP server that pairs auto‑managed, zero‑config loc
 }
 ```
 
-**Claude Code** — run this command:
+**Claude Code** — install the plugin (recommended, includes workflow skills for best results):
+
+```bash
+claude plugin add --from-github giancarloerra/socraticode
+```
+
+Or as MCP only (without skills):
 
 ```bash
 claude mcp add socraticode -- npx -y socraticode
@@ -100,13 +118,15 @@ Restart your host. On first use SocratiCode automatically pulls Docker images, s
 
 > **Recommended**: For best results, add the [Agent Instructions](#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 — 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](#configuration) below.
 
 ## 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.
 
-- **True Zero Configuration** — Just add the MCP server to your AI host config. The server automatically pulls Docker images, starts Qdrant and Ollama containers, and downloads the embedding model on first use. No config files, no YAML, no environment variables to tune, no native dependencies to compile, no commands to type. Works everywhere Docker runs.
+- **True Zero Configuration** — Just install the Claude Plugin/Skill or add the MCP server to your AI host config. The server automatically pulls Docker images, starts Qdrant and Ollama containers, and downloads the embedding model on first use. No config files, no YAML, no environment variables to tune, no native dependencies to compile, no commands to type. Works everywhere Docker runs.
 - **Fully Private & Local by Default** — Everything runs on your machine. Your code never leaves your network. The default Docker setup includes Ollama and Qdrant with no external API calls. Optional cloud providers (Qdrant, OpenAI, Gemini) are available but never required.
 - **Language-Agnostic** — Works with every programming language, framework, and file type out of the box. No per-language parsers to install, no grammar files to maintain, no "unsupported language" limitations. If your AI can read it, SocratiCode can index it.
 - **Production-Grade Vector Search** — Built on Qdrant, a purpose-built vector database with HNSW indexing, concurrent read/write, and payload filtering. Collections store both a dense vector and a BM25 sparse vector per chunk; the Query API runs both sub-queries in a single round-trip and fuses results with RRF. Designed for scale vector search.
@@ -140,7 +160,7 @@ I built SocratiCode because I regularly work on existing, large, and complex cod
 - **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_status` reports "active (watched by another process)" instead of incorrectly showing "inactive."
 - **Concurrency guards** — Duplicate indexing and graph-build operations are prevented. If you call `codebase_index` while 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-run `codebase_index` to resume from where it left off.
-- **Graceful shutdown** — On server shutdown, active indexing operations are given up to 60 seconds to complete, all file watchers are stopped cleanly, and the MCP server closes gracefully.
+- **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.
 
@@ -201,6 +221,8 @@ User: "Are there any circular dependencies?"
 
 ## 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 system prompt, `CLAUDE.md`, `AGENTS.md`, or equivalent 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.
 
 ```markdown
@@ -270,7 +292,45 @@ before reading any files directly.
 
 ### Install
 
-#### npx (recommended — no installation)
+#### Claude Code plugin (recommended for Claude Code users)
+
+The SocratiCode plugin bundles both the MCP server and workflow skills that teach Claude how to use the tools effectively. One install gives you everything:
+
+```bash
+claude plugin add --from-github giancarloerra/socraticode
+```
+
+The plugin includes:
+- **MCP server** — all 21 SocratiCode tools (search, graph, context artifacts, etc.)
+- **Exploration skill** — teaches Claude the search-before-reading workflow
+- **Management skill** — guides setup, indexing, watching, and troubleshooting
+- **Explorer agent** — delegatable subagent for deep codebase analysis
+
+> If you previously installed SocratiCode as a standalone MCP (`claude mcp add socraticode`), remove it after installing the plugin to avoid duplicates: `claude mcp remove socraticode`
+
+**Configuring environment variables:** SocratiCode works with zero config for most users (local Ollama + managed Qdrant). If you need cloud embeddings, a remote Qdrant, or other customization:
+
+1. **Claude Code settings** (recommended) — add to `~/.claude/settings.json`:
+   ```json
+   {
+     "env": {
+       "EMBEDDING_PROVIDER": "openai",
+       "OPENAI_API_KEY": "sk-..."
+     }
+   }
+   ```
+   This works in all environments — CLI, VS Code, and JetBrains.
+
+2. **Shell profile** — set vars in `~/.zshrc` or `~/.bashrc`:
+   ```bash
+   export EMBEDDING_PROVIDER=openai
+   export OPENAI_API_KEY=sk-...
+   ```
+   Works when Claude Code is launched from a terminal. Note: IDE-launched sessions (e.g. VS Code opened from Finder/Dock) may not inherit shell profile variables — use option 1 instead.
+
+Restart Claude Code after changing variables. See [Environment Variables](#environment-variables) for all options.
+
+#### npx (recommended for all other MCP hosts — no installation)
 
 Requires Node.js 18+ and Docker (running). Already covered in [Quick Start](#quick-start) above, add the following to your `mcpServers` (Claude Desktop, Windsurf, Cline, Roo Code) or `servers` (VS Code project-local `.vscode/mcp.json`) config:
 

diff --git a/agents/codebase-explorer.md b/agents/codebase-explorer.md
@@ -0,0 +1,53 @@
+---
+name: codebase-explorer
+description: >-
+  Deep codebase exploration using SocratiCode. Combines semantic search,
+  dependency graphs, and context artifacts to answer questions about code
+  structure and behavior. Use when delegating complex codebase understanding
+  tasks that require tracing through multiple files and dependencies.
+
+  <example>
+  Context: User wants to understand how a complex feature works across multiple files.
+  user: "How does the authentication system work in this codebase?"
+  assistant: "I'll use the codebase-explorer agent to trace through the authentication implementation."
+  </example>
+
+  <example>
+  Context: User wants an architectural overview of a new codebase.
+  user: "Give me an overview of this project's architecture"
+  assistant: "I'll use the codebase-explorer agent for a deep architectural analysis."
+  </example>
+model: sonnet
+allowed-tools: Read, Grep, Glob, Bash(git *)
+---
+
+You are a codebase exploration specialist. You use SocratiCode's MCP tools to understand codebases deeply and efficiently.
+
+## Core Principle: Search Before Reading
+
+Never open a file just to check if it's relevant. Always search first.
+
+## Your Approach
+
+1. **Search broadly first.** Use `codebase_search` with conceptual queries to map the relevant areas of the codebase. A single search returns ranked snippets from the entire codebase in milliseconds.
+
+2. **Follow the dependency graph.** Use `codebase_graph_query` to understand what a file imports and what depends on it before reading its contents. Use `codebase_graph_stats` for an architectural overview.
+
+3. **Check for non-code knowledge.** Use `codebase_context` to discover database schemas, API specs, and infrastructure configs. Use `codebase_context_search` to search them.
+
+4. **Read files only after narrowing down.** Once search results point to 1-3 specific files, read the relevant sections.
+
+5. **Check for architectural issues.** Use `codebase_graph_circular` to detect circular dependencies when debugging unexpected behavior.
+
+6. **Synthesize findings.** Present clear, structured answers with specific file paths and line references. Explain the relationships between components.
+
+## Available SocratiCode Tools
+
+**Search:** `codebase_search` (hybrid semantic + keyword), `codebase_status`
+**Graph:** `codebase_graph_query`, `codebase_graph_stats`, `codebase_graph_circular`, `codebase_graph_visualize`, `codebase_graph_status`
+**Context:** `codebase_context`, `codebase_context_search`
+**Info:** `codebase_about`
+
+## When to Use grep Instead
+
+If you already know the exact identifier, error string, or regex pattern, use grep/ripgrep — it's faster and more precise for exact matches. Use `codebase_search` when exploring conceptually or when you don't know which files to look in.
diff --git a/hooks/hooks.json b/hooks/hooks.json
@@ -0,0 +1,14 @@
+{
+  "SessionStart": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "IMPORTANT: If you notice that SocratiCode MCP tools appear with BOTH a plugin prefix (e.g. mcp__plugin_socraticode_socraticode__codebase_search) AND a standalone prefix (e.g. mcp__socraticode__codebase_search), the user has a duplicate configuration. Advise them to remove the standalone MCP by running: claude mcp remove socraticode — the plugin already provides the MCP server.",
+          "timeout": 5
+        }
+      ]
+    }
+  ]
+}
diff --git a/package.json b/package.json
@@ -50,6 +50,11 @@
   "license": "AGPL-3.0-only",
   "files": [
     "dist",
+    ".claude-plugin",
+    "skills",
+    "agents",
+    "hooks",
+    ".mcp.json",
     "LICENSE",
     "LICENSE-COMMERCIAL",
     "README.md",