mirror of
https://github.com/giancarloerra/socraticode.git
synced 2026-06-01 22:18:57 +02:00
feat: multi-platform plugin support (Cursor, Codex, Gemini CLI, VS Code)
This commit is contained in:
Giancarlo Erra
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"name": "socraticode",
|
||||
"version": "1.4.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"
|
||||
],
|
||||
"skills": "./skills/",
|
||||
"mcpServers": "./.mcp.json",
|
||||
"interface": {
|
||||
"displayName": "SocratiCode",
|
||||
"shortDescription": "Codebase intelligence — semantic search, dependency graphs, and context artifacts",
|
||||
"longDescription": "SocratiCode provides codebase intelligence through semantic search workflows, dependency graph analysis, and context artifact exploration. Index your codebase, search with hybrid semantic + keyword search, visualize module dependencies, and manage context artifacts.",
|
||||
"developerName": "Giancarlo Erra",
|
||||
"category": "Development",
|
||||
"capabilities": ["Read"],
|
||||
"websiteURL": "https://github.com/giancarloerra/socraticode",
|
||||
"privacyPolicyURL": "https://github.com/giancarloerra/socraticode/blob/main/SECURITY.md",
|
||||
"termsOfServiceURL": "https://github.com/giancarloerra/socraticode/blob/main/LICENSE",
|
||||
"defaultPrompt": [
|
||||
"Use SocratiCode to search the codebase for authentication handling.",
|
||||
"Use SocratiCode to visualize the dependency graph of this project."
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"name": "socraticode",
|
||||
"owner": {
|
||||
"name": "Giancarlo Erra",
|
||||
"email": "giancarlo@altaire.com"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "SocratiCode — codebase intelligence plugin"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "socraticode",
|
||||
"source": "./",
|
||||
"description": "Codebase intelligence — semantic search workflows, dependency graph analysis, and context artifact exploration",
|
||||
"category": "development"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "socraticode",
|
||||
"version": "1.4.1",
|
||||
"description": "Codebase intelligence — semantic search workflows, dependency graph analysis, and context artifact exploration for SocratiCode",
|
||||
"author": {
|
||||
"name": "Giancarlo Erra",
|
||||
"email": "giancarlo@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"
|
||||
],
|
||||
"skills": "./skills/",
|
||||
"mcpServers": "./.mcp.json"
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
## 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.
|
||||
|
||||
3. **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.
|
||||
|
||||
4. **Use `codebase_graph_circular` when debugging unexpected behavior.**
|
||||
Circular dependencies cause subtle runtime issues; check for them proactively.
|
||||
|
||||
5. **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.
|
||||
|
||||
6. **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` |
|
||||
| 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_search` call 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.
|
||||
@@ -31,7 +31,7 @@
|
||||
|
||||
> 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, cross-project 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.
|
||||
**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, cross-project 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 native **plugin** for Claude Code, Cursor, VS Code Copilot, Codex or Gemini CLI. 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.
|
||||
|
||||
@@ -54,6 +54,7 @@ The first Qdrant‑based MCP/Claude Plugin/Skill that pairs auto‑managed, zero
|
||||
## Contents
|
||||
|
||||
- [Quick Start](#quick-start)
|
||||
- [Plugins](#plugins)
|
||||
- [Why SocratiCode](#why-socraticode)
|
||||
- [Features](#features)
|
||||
- [Prerequisites](#prerequisites)
|
||||
@@ -152,6 +153,39 @@ Restart your host. On first use SocratiCode automatically pulls Docker images, s
|
||||
|
||||
> **Advanced**: cloud embeddings (OpenAI / Google), external Qdrant, remote Ollama, native Ollama, and dozens of tuning options are all available. See [Configuration](#configuration) below.
|
||||
|
||||
## Plugins
|
||||
|
||||
SocratiCode is available as a native plugin on multiple AI coding platforms. Plugins bundle the MCP server with workflow skills and agent instructions — one install gives you everything.
|
||||
|
||||
| Platform | Install method |
|
||||
|:---------|:---------------|
|
||||
| Claude Code | `claude plugin marketplace add giancarloerra/socraticode` — [full instructions](#claude-code-plugin-recommended-for-claude-code-users) |
|
||||
| Cursor | `/add-plugin https://github.com/giancarloerra/socraticode` |
|
||||
| VS Code Copilot | Command Palette → `Chat: Install Plugin From Source` → `https://github.com/giancarloerra/socraticode` |
|
||||
| Gemini CLI | `gemini extensions install https://github.com/giancarloerra/socraticode` |
|
||||
| OpenAI Codex | No public plugin directory yet — use the [MCP config](#quick-start) or [install locally](#codex-local-plugin-install) |
|
||||
|
||||
> **VS Code Copilot**: The chat plugins feature is in preview. Enable it with `chat.plugins.enabled: true` in your VS Code settings.
|
||||
|
||||
> **Codex local plugin install**: Clone the repo and register it in your personal plugin marketplace:
|
||||
> ```bash
|
||||
> git clone https://github.com/giancarloerra/socraticode.git ~/.agents/plugins/socraticode
|
||||
> ```
|
||||
> Then add it to `~/.agents/plugins/marketplace.json`:
|
||||
> ```json
|
||||
> {
|
||||
> "plugins": [
|
||||
> {
|
||||
> "name": "socraticode",
|
||||
> "path": "~/.agents/plugins/socraticode"
|
||||
> }
|
||||
> ]
|
||||
> }
|
||||
> ```
|
||||
> Codex will discover the plugin from `.codex-plugin/plugin.json` on next launch.
|
||||
|
||||
> **All other MCP hosts** (Claude Desktop, Windsurf, Cline, Roo Code, OpenCode): Use the [MCP config](#quick-start) — works with any host that supports the MCP protocol.
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -17,8 +17,6 @@ description: >-
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "socraticode",
|
||||
"version": "1.4.1",
|
||||
"contextFileName": "GEMINI.md",
|
||||
"mcpServers": {
|
||||
"socraticode": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "socraticode"]
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user