docs(extension): editor-neutral marketplace README with hero, badges and benchmarks

The marketplace listing page is the single biggest conversion surface
for the extension. This pass turns the README into something that
reads as a polished product page, not an in-house engineering note.

Headline changes:

- Editor-neutral framing throughout. The same `.vsix` ships to VS
  Code, Cursor, VSCodium, Gitpod, code-server, Theia, Antigravity,
  and Particle Workbench. The previous wording was VS Code-first
  (Copilot agent mode listed first, "VS Code's MCP host", title with
  "for VS Code"). Replaced with editor-agnostic language: "any
  MCP-compatible chat or agent in your editor", followed by named
  surfaces (Copilot agent mode, Cursor's Agent / Composer, the
  Gemini surface in Antigravity, Cline, Continue, Roo Code, others).
- Hero image referenced via raw GitHub URL (absolute, survives both
  marketplace renderers).
- Badge row: VS Code Marketplace version + installs, Open VSX
  version + downloads, GitHub stars, npm engine version, license.
  Marketplace badges 404 until first publish; that's expected.
- Prominent "Full documentation, configuration reference, and
  benchmarks on GitHub" link directly under the badges. The extension
  README is intentionally short; the engine README is the deep doc.
- Headline benchmark callout up top: 61% less context, 84% fewer
  tool calls, 37x faster on the 2.45M-line VS Code codebase, with a
  direct anchor link to the full benchmark.
- New "Why bigger teams pick it" section covering refactor safety
  on monorepos, multi-repo orgs, tool-independence, air-gapped
  deployment, AGPL-3.0 transparency, and the 18+ language list.
- Compatibility section now lists every editor and every AI surface
  explicitly, so a Cursor or Antigravity user can recognise their
  setup without reading between the lines.
- Settings table simplified around the four real settings, with
  `socraticode.env` documented as the single passthrough for every
  engine knob (external Qdrant, embedding providers, project IDs,
  branch-aware indexing, linked projects).

Manifest tweak:

- Add `galleryBanner` (`#3a3d8c` brand colour, dark theme) so the
  Marketplace listing's hero strip matches the icon and the project
  website rather than defaulting to grey.

Build, lint, typecheck and the manifest smoke tests are all clean.
Packaged size 216 KB.
This commit is contained in:
Giancarlo Erra
2026-05-03 21:02:03 +01:00
parent d9459f8591
commit 345c7281d0
2 changed files with 150 additions and 57 deletions
+146 -57
View File
@@ -1,95 +1,184 @@
# SocratiCode for VS Code (and Cursor, VSCodium, Gitpod, code-server, Antigravity, Theia, ...)
<p align="center">
<img src="https://raw.githubusercontent.com/giancarloerra/socraticode/main/socraticode_logo.png" alt="SocratiCode" width="160">
</p>
**Codebase context engine for AI assistants.** SocratiCode indexes your
repositories: code, dependency and call graphs, database schemas, API
specs, architecture docs. It hands that understanding to whichever AI
assistant you use, so the same understanding survives every tool switch.
<h1 align="center">SocratiCode</h1>
This extension auto-registers the SocratiCode MCP server in VS Code's MCP
host so it works out of the box with **Copilot agent mode**, **Cline**,
**Continue**, **Roo Code**, and any other MCP-compatible chat or agent
extension. No `mcp.json` editing required.
<p align="center"><strong>The codebase context engine for AI assistants.</strong><br>
Same understanding of your code, every assistant, every tool switch.</p>
<p align="center">
<a href="https://marketplace.visualstudio.com/items?itemName=altaire.socraticode"><img src="https://img.shields.io/visual-studio-marketplace/v/altaire.socraticode?style=flat-square&logo=visualstudiocode&logoColor=white&label=VS%20Code%20Marketplace" alt="VS Code Marketplace"></a>
<a href="https://marketplace.visualstudio.com/items?itemName=altaire.socraticode"><img src="https://img.shields.io/visual-studio-marketplace/i/altaire.socraticode?style=flat-square&label=installs" alt="Installs"></a>
<a href="https://open-vsx.org/extension/altaire/socraticode"><img src="https://img.shields.io/open-vsx/v/altaire/socraticode?style=flat-square&label=Open%20VSX" alt="Open VSX"></a>
<a href="https://open-vsx.org/extension/altaire/socraticode"><img src="https://img.shields.io/open-vsx/dt/altaire/socraticode?style=flat-square&label=downloads" alt="Open VSX Downloads"></a>
<a href="https://github.com/giancarloerra/socraticode"><img src="https://img.shields.io/github/stars/giancarloerra/socraticode?style=flat-square&logo=github&label=stars" alt="GitHub stars"></a>
<a href="https://www.npmjs.com/package/socraticode"><img src="https://img.shields.io/npm/v/socraticode?style=flat-square&logo=npm&label=engine" alt="npm engine"></a>
<a href="https://github.com/giancarloerra/socraticode/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square" alt="License"></a>
</p>
<p align="center">
<strong><a href="https://github.com/giancarloerra/socraticode#readme">Full documentation, configuration reference, and benchmarks on GitHub →</a></strong>
</p>
---
> **The big number.** On a 2.45M-line codebase, SocratiCode answers the same architectural question with **61% less context burned**, **84% fewer tool calls**, and **37x faster** than a grep-based AI agent. Same model, dramatically better answers. [Full benchmark on GitHub.](https://github.com/giancarloerra/socraticode#real-world-benchmark-vs-code-245m-lines-of-code-with-claude-opus-46)
This extension auto-registers the SocratiCode MCP server in any
MCP-compatible chat or agent in your editor, with no `mcp.json` editing
required. The same `.vsix` ships to the VS Code Marketplace and the
Open VSX Registry, so it works the same way in **VS Code, Cursor,
VSCodium, Gitpod, code-server, Eclipse Theia, Google Antigravity, and
Particle Workbench**.
## What it does
- **Hybrid search** (semantic + BM25, RRF-fused) across your codebase.
- **Hybrid search** (semantic + BM25, fused via Reciprocal Rank Fusion).
Tested on codebases over 40 million lines.
- **File-level dependency graphs** across 18+ languages with circular-
dependency detection.
- **Symbol-level call graph and impact analysis**: answers "what breaks if
I change function X?" before the AI changes it.
- **Cross-repo search** across multiple linked projects.
- **Interactive graph viewer** with blast-radius overlay, search, and PNG
export. Opens directly inside the editor as a webview panel.
- **Context artefacts**: index database schemas, API specs and architecture
docs alongside code. The AI sees the schema your developer team did, not
what it guessed from filenames.
- **Symbol-level call graph and impact analysis**: answers
*"what breaks if I change function X?"* before the AI changes it.
- **Call-flow tracing** from any entry point, so onboarding to a
legacy module takes minutes instead of days.
- **Cross-repo search** across linked workspaces. The bug is in the
API gateway and the AI is looking at the front-end? It sees the
full system in one query.
- **Interactive graph viewer** with blast-radius overlay, search,
click-to-open-file, and PNG export. Opens directly inside the editor
as a webview panel.
- **Context artefacts**: index database schemas, API specs and
architecture docs alongside code. The AI sees the schema your team
designed, not what it guessed from filenames.
- **Branch-aware indexing**: every branch gets its own index, so PR
reviews see the code actually being reviewed.
## Requirements
## Why bigger teams pick it
- VS Code 1.99 or newer (for native MCP support)
- Node.js 18+ on PATH (for `npx` to launch the engine)
- Docker Desktop running (the engine uses Docker for Qdrant + Ollama
containers; alternatively you can point at an external Qdrant via
the `socraticode.env` setting).
- **Refactor safety on a monorepo.** Blast-radius analysis surfaces
every file and symbol that calls into a target before any change
goes in. Particularly useful in regulated and legacy contexts.
- **Multi-repo orgs.** Cross-project search treats your microservices
as one searchable surface, not N disconnected repos.
- **Tool-independent.** Move from Cursor to Copilot to Cline to
whatever ships next. The index, dependency graphs and context
artefacts survive every tool switch. No vendor lock-in.
- **Air-gapped friendly.** The default deployment runs entirely on
your machine via Docker (Qdrant + Ollama). Code never leaves the
network unless you explicitly point at an external service via the
`socraticode.env` setting.
- **Open source at the core (AGPL-3.0).** Battle-tested across thousands
of repositories. Every component that touches your code is inspectable.
- **18+ languages out of the box.** TypeScript, JavaScript, Python, Go,
Rust, Java, Kotlin, Scala, C#, C, C++, Ruby, PHP, Swift, Bash, Dart,
Lua, Svelte, Vue, plus 35+ plain-text formats.
## Compatibility
**Editors.** This extension installs in any editor that supports the
VS Code 1.99+ extension API:
- Microsoft VS Code (Stable / Insiders)
- Cursor
- VSCodium
- Gitpod
- code-server
- Eclipse Theia based editors
- Google Antigravity
- Particle Workbench
**AI surfaces.** The MCP server registered by this extension is
discovered automatically by any MCP-compatible chat or agent installed
in your editor:
- GitHub Copilot agent mode
- Cursor's Agent / Composer
- The Gemini chat surface in Antigravity
- [Cline](https://github.com/cline/cline)
- [Continue](https://www.continue.dev/)
- [Roo Code](https://roo.tech/)
- Any other MCP-aware client, including ones not listed here
If your editor or AI surface speaks MCP, SocratiCode shows up.
## Quick start
1. Install the extension.
2. The MCP server registers automatically. Ask Copilot agent mode (or any
MCP-aware assistant) a question about your codebase.
3. Open the SocratiCode sidebar (Activity Bar → SocratiCode icon) and click
**Index this workspace** to run the first index.
4. Open the interactive graph from the Command Palette: `SocratiCode: Open
interactive graph`.
1. **Install the extension.** Search **SocratiCode** in your editor's
Extensions panel. The MCP server registers automatically.
2. **Index the workspace.** Open the SocratiCode sidebar (Activity Bar
icon) and click *Index this workspace*. The first index downloads
the embedding model; subsequent updates are incremental.
3. **Ask anything.** Use your AI assistant: "where is auth handled?",
"what breaks if I change `processOrder`?", "trace the nightly cron
job", "what tables does this API touch?".
4. **Open the interactive graph.** Command Palette →
`SocratiCode: Open interactive graph`.
A walkthrough is shown on first install. Re-open it any time with
A walkthrough is shown on first install; re-open it any time via
`SocratiCode: Open getting-started walkthrough`.
## Requirements
- An editor on the VS Code 1.99+ API (any of the editors listed above).
- Node.js 18+ on `PATH` (the engine launches via `npx`).
- Docker Desktop running (for the default local engine), OR a
reachable external Qdrant if you'd rather not use Docker (configured
via `socraticode.env`, see Settings).
## Commands
All commands are also available under `SocratiCode:` in the Command Palette.
All commands appear under `SocratiCode:` in the Command Palette.
- **Index current workspace**: kick off a one-time index.
- **Open interactive graph**: render the dependency / call graph as an
in-editor webview.
- **Refresh indexed projects**: reload the sidebar tree.
- **Open getting-started walkthrough**: replay the onboarding.
- **Show output / logs**: open the SocratiCode output channel.
- `SocratiCode: Index current workspace`: kick off a one-time index.
- `SocratiCode: Open interactive graph`: render the dependency / call
graph as an in-editor webview.
- `SocratiCode: Refresh indexed projects`: reload the sidebar tree.
- `SocratiCode: Open getting-started walkthrough`: replay the onboarding.
- `SocratiCode: Show output / logs`: open the SocratiCode output channel.
## Settings
| Setting | Default | Description |
| Setting | Default | Purpose |
|---|---|---|
| `socraticode.command` | `"npx"` | Engine launcher. |
| `socraticode.args` | `["-y", "socraticode"]` | Args for the launcher. |
| `socraticode.env` | `{}` | Environment variables forwarded to the engine. Use this for external Qdrant (`QDRANT_MODE=external`, `QDRANT_URL`, `QDRANT_API_KEY`), embedding provider (`EMBEDDING_PROVIDER`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`), or any other engine setting documented in the engine README. |
| `socraticode.env` | `{}` | Environment variables forwarded to the engine. Use this to point at an external Qdrant cluster (`QDRANT_MODE=external`, `QDRANT_URL`, `QDRANT_API_KEY`), pick an embedding provider (`EMBEDDING_PROVIDER`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`), enable branch-aware indexing, link multiple projects, or set any other engine knob from the [engine README](https://github.com/giancarloerra/socraticode#configuration). |
| `socraticode.statusBar` | `true` | Show the status-bar item. |
## Privacy and data
- The engine indexes locally. Code never leaves your machine unless you
explicitly point it at an external service via `socraticode.env`.
- The engine indexes locally by default. Code never leaves your
machine unless you explicitly configure an external service via
`socraticode.env`.
- No telemetry from the extension.
- The engine is open source under AGPL-3.0; every component that
touches your code is inspectable.
## Open source
## Learn more
The engine is open source under AGPL-3.0 and battle-tested across
thousands of indexed repositories. That openness is your guarantee of
transparency, security and engineering quality.
The extension is the install surface. The full picture lives in the
project repo:
- Repository: https://github.com/giancarloerra/socraticode
- Issues / questions: https://github.com/giancarloerra/socraticode/issues
- **[Full README, configuration reference, and benchmark methodology](https://github.com/giancarloerra/socraticode#readme)**
- [Issues and feature requests](https://github.com/giancarloerra/socraticode/issues)
- [Discord community](https://discord.gg/5DrMXfNG)
## Troubleshooting
- **"Cannot find Docker"**: install Docker Desktop from
https://docker.com/products/docker-desktop, or set `socraticode.env`
with `QDRANT_MODE=external` plus `QDRANT_URL` to point at an existing
Qdrant.
- **MCP tools don't appear in Copilot agent mode**: restart the chat
after install, or run `MCP: List Servers` from the command palette and
with `QDRANT_MODE=external` plus `QDRANT_URL` to use an existing
Qdrant instance.
- **MCP tools don't appear in your assistant**: restart the chat after
install, or run `MCP: List Servers` from the command palette and
confirm `SocratiCode` is listed and started.
- **First index is slow**: the engine downloads Ollama models the first
time. Subsequent runs are fast.
- See `SocratiCode: Show output / logs` in the command palette for engine
output.
- **First index is slow**: the engine downloads the embedding model
the first time. Subsequent runs are fast.
- **Anything else**: `SocratiCode: Show output / logs` from the
command palette has the engine output.
## License
[AGPL-3.0-only](https://github.com/giancarloerra/socraticode/blob/main/LICENSE).
The engine and this extension are open source.
+4
View File
@@ -6,6 +6,10 @@
"publisher": "altaire",
"license": "AGPL-3.0-only",
"icon": "images/icon.png",
"galleryBanner": {
"color": "#3a3d8c",
"theme": "dark"
},
"engines": {
"vscode": "^1.99.0",
"node": ">=18.0.0"