CodeExplain

CI: GitHub Actions

Explain code in plain language as it's being written — so non-technical people can actually understand what vibe-coded apps do.

CodeExplain is a harness that watches Python, JavaScript, and TypeScript source and translates it into human-readable explanations. It ships as a VS Code extension and as an MCP server + CLI for coding agents, sharing one standalone, testable TypeScript core.

What it does

• Function summaries — when a function is written or changed, show a plain-English "what this does" summary.

• Risk alerts — instantly warn on dangerous patterns (DELETE FROM, DROP TABLE, fs.unlink, rm -rf) with a "this can't be undone" style warning.

• On-demand deep dive — select any code and ask for a full, pedagogical explanation.

• Model fallback — uses a local model (Ollama) by default and falls back to a cloud API when needed.

Related MCP server: Code Search MCP

Install & setup

Prerequisites

Risk alerts and the function/import list run fully offline — no model, no network. Explanations need either a local Ollama server or a cloud API key (see settings), and degrade gracefully when neither is reachable.

Option A — VS Code extension

npm install
npm run build && npm run build:extension   # compile + bundle the extension
npm run package                            # produces code-explain-<version>.vsix

Install the resulting .vsix via Extensions → … → Install from VSIX…, then open the CodeExplain view from the activity bar. Developers can instead press F5 to launch an Extension Development Host.

Option B — CLI & coding agent (MCP)

No install needed to try it:

npx -y code-explain mcp install --client cursor --scope project   # preview

From a local checkout, build once and point --local at the compiled CLI:

npm install && npm run build
node dist/cli.js mcp install --client cursor --local "$PWD/dist/cli.js"

See Use it from your coding agent for the full mcp install flow, supported agents, and the four MCP tools.

Architecture

The harness works in three layers:

1. Parser — parses code into a structured tree (via web-tree-sitter) so it understands logic flow, not just keywords. Handles Python, JS, and TS uniformly.

2. Analyzer — determines why the code exists: what a function does, what a statement is for, and whether anything looks destructive.

3. Translator (LLM) — turns the structured data into plain, cautious, human-readable explanations.

Two kinds of analysis:

• Risk detection is rule-based and runs offline — instant, deterministic, free (no LLM call).

• Explanations call the model with a strict prompt that returns JSON {summary, risk, level} in a friendly, fifth-grade tone.

Tech stack

• TypeScript — core library, no editor dependencies

• web-tree-sitter (WASM) — parses Python / JS / TS

• OpenAI-compatible /chat/completions client — cloud fallback

• Ollama — local model path

• vitest — unit tests

Build order / status

Phase 1 — testable core:

• Parser + extractor (tree-sitter)

• Risk analyzer (offline rules)

• LLM provider (local → cloud fallback) + prompt builder

• Demo CLI: explain <file.py|.js|.ts> prints summaries + risk warnings

• Unit tests (vitest)

Phase 2 — VS Code extension:

• Debounced watcher (~1.5s after typing)

• Sidebar webview panel (per-function summaries + risk alerts)

• Inline hover + CodeLens

• On-demand command ("CodeExplain: Explain selection", also in the editor context menu)

• Settings (codeExplain.*) and a loadable CommonJS bundle

Phase 3 — beautiful panel & packaging:

• Premium dark "liquid glass" sidebar design (translucent cards, specular highlights, drifting aurora backdrop, staggered entrance motion)

• Click a card to jump to its line; risk cards show the matched snippet

• Package a .vsix (npm run package) for manual install

Phase 4 — agent plug-in (MCP):

• MCP stdio server (code-explain mcp) exposing list_functions, scan_risks, explain_code, and explain_changes

• explain_changes derives git diff HEAD ranges when none are supplied

• One-command client setup: code-explain mcp install --client <id>

Phase 5 — explain only what changed:

• On save, the extension re-explains only the functions touching changed lines (structure + risks still update live while typing)

• Explanations cached by function signature, so repeat saves are free

Phase 6 — distribution:

• mcp install prints/writes config for 13 clients (no file touched unless --write); --local launches a local build without publishing

• Lean npm package (built dist/ + docs) with executable bin entries

Using the extension

Open the CodeExplain view in the activity bar (rocket icon) to see live explanations for the active file. Hover a function or use its CodeLens for a quick summary, or run CodeExplain: Explain selection from the Command Palette / right-click menu.

While you type, the panel refreshes the function list and risk alerts live (no model call). When you save, CodeExplain runs git diff and explains only the functions you actually changed — so summaries stay fast and never re-explain untouched code.

The panel uses a self-contained dark, premium glass theme (no external assets), so it looks the same under any VS Code color theme and honors prefers-reduced-motion.

Key settings (all under codeExplain.*):

Use it from your coding agent (MCP)

CodeExplain also runs as a Model Context Protocol server over stdio, so a coding agent can ask it to explain files without leaving the chat. One server, four tools:

explain_changes takes an optional changed list of {startLine, endLine} ranges (0-based, inclusive); when omitted it derives them from git diff HEAD for that file. Each tool accepts format: "text" | "json".

One-command setup

# See which agents CodeExplain can configure
npx -y code-explain mcp install --list

# Preview the exact config for your agent (prints, never edits a file)
npx -y code-explain mcp install --client cursor --scope project

# Write it in place
npx -y code-explain mcp install --client codex --write

Supported clients: claude, cursor, cline, windsurf, vscode, opencode, zed, codex, continue, hermes, deepseek-harness, pi, grok.

By default mcp install prints the snippet and target path and touches nothing; pass --write to merge the entry in. Use --force to replace an existing entry of the same name, --scope user|project to choose where it lands, and --local /path/to/dist/cli.js to launch a local build with node instead of npx (handy before you publish). If your agent isn't listed, run without --write and paste the printed snippet yourself.

Running the server directly

npx -y code-explain mcp        # start the stdio server

stdout is the JSON-RPC channel — the server only ever writes logs to stderr.

Development

npm install
npm run build            # type-check + emit library (tsc)
npm run build:extension  # bundle the extension (esbuild → dist/extension.cjs)
npm test                 # vitest
npm run explain -- test/fixtures/app.py [--llm]

node dist/cli.js mcp                                # run the MCP stdio server
node dist/cli.js mcp install --client cursor        # preview a client config
npm run package                                     # build code-explain-<version>.vsix

The extension bundle is CommonJS (dist/extension.cjs) so it loads on VS Code ^1.86.0; esbuild maps import.meta.url to __filename for the tree-sitter loader. Press F5 in VS Code to launch an Extension Development Host.

Roadmap notes

• Real-time means debounced, not every keystroke — trigger after a short pause and cancel in-flight calls if the user keeps typing.

• Only summarize functions that actually changed; cache by (file + function-signature) hash; cap concurrent calls.

• For private code, prefer the local model so source never leaves the machine.

License

MIT — see LICENSE.

Copyright (c) 2026 RevTheDev Systems.