CodeClone for VS Code
Native VS Code surface for codeclone-mcp.
Brings baseline-aware structural analysis into the editor — triage-first, read-only,
and driven by the same canonical report as the CLI and HTML output.
Not a linter panel. CodeClone for VS Code is designed for structural review and
refactoring flow, not diagnostics or Problems integration.
Features
- Hotspots view — new regressions, production hotspots, and changed-files findings
at a glance; report-only Security Surfaces and Overloaded Modules kept visually separate
- Baseline-aware — distinguishes known debt from new regressions against the stored baseline
- Changed-files review —
Review Changes scopes analysis to the current diff via a configurable git ref
- Coverage Join — integrates
coverage.xml to surface untested hotspots when available
- Source-first navigation —
Reveal Source opens the exact location; Next / Previous Hotspot
steps through active targets in the editor
- Lightweight decorations — Explorer file decorations and CodeLens appear only where relevant;
no sidebar duplication of the HTML report
Open in HTML Report — explicit bridge to the full report when a fresh local report.html exists
Requirements
- VS Code
1.85+
- Python workspace (trusted)
codeclone-mcp launcher (codeclone >= 2.0.0)
Install
Install the codeclone-mcp launcher before enabling the extension.
Recommended (global tool via uv):
uv tool install "codeclone[mcp]"
Current environment only:
uv pip install "codeclone[mcp]"
Verify:
codeclone-mcp --help
In auto mode the extension checks the current workspace virtualenv first,
then falls back to PATH. Version-mismatch messages identify the resolved launcher source.
Getting started
- Open a trusted Python workspace.
- Open the CodeClone view container.
- Run Analyze Workspace.
- Start with Review Priorities or Review Changes as the first pass.
- To tune sensitivity, open Set Analysis Depth.
If the launcher is missing, use Open Setup Help from the view or the command palette.
Main views
Overview
Compact repository health, current run state, baseline drift, and the next recommended
review action.
Hotspots
The primary operational view. Surfaces:
- new regressions and production hotspots
- changed-files findings against the configured diff ref
- Coverage Join items when
coverage.xml is available
- report-only Security Surfaces (boundary inventory, not vulnerability claims)
- report-only Overloaded Module candidates
Focus mode is explicit and persisted per workspace; Recommended is the default.
Runs & Session
Bounded MCP session state: server availability, current run identity, reviewed findings,
and help topics. Reviewed markers are session-local and do not mutate the repository or report.
Settings
| Setting |
Default |
Scope |
Description |
codeclone.mcp.command |
auto |
Machine |
Launcher used to start the local CodeClone server. auto checks workspace virtualenv, then PATH. |
codeclone.mcp.args |
[] |
Machine |
Extra arguments passed to the launcher. |
codeclone.analysis.cachePolicy |
— |
Resource |
Default cache policy for analysis requests. Can differ per workspace or folder. |
codeclone.analysis.changedDiffRef |
— |
Resource |
Git revision used by Review Changes. |
codeclone.analysis.profile |
conservative |
Resource |
Analysis sensitivity. Use deeper or custom only as deliberate follow-ups. |
codeclone.analysis.minLoc |
— |
Resource |
Function/block/segment thresholds — active only when profile is custom. |
codeclone.analysis.coverageXml |
— |
Resource |
Path to coverage.xml. Auto-detects workspace-root file when unset. |
codeclone.ui.showStatusBar |
true |
Window |
Show or hide the workspace-level status bar item. |
Limitations
- No background analysis on save; no VS Code Problems / diagnostics integration.
- Reviewed markers are session-local only.
Open in HTML Report requires a local report.html that is fresh for the current run.- Virtual workspaces are not supported.
Trust model
The extension accesses local filesystem and git state to run structural analysis.
Untrusted workspaces are supported in a limited setup/onboarding mode only;
full analysis and MCP are disabled until workspace trust is granted.
Design decisions
- No second truth model — health, findings, and drift come exclusively from
codeclone-mcp and canonical report semantics.
- Read-only — the extension never edits source files, baselines, caches, or report artifacts.
- Report-only separation — Security Surfaces and Overloaded Modules are visible but
intentionally excluded from findings, gates, and health scoring.
- Source-first — the default review action moves you to code before opening deeper detail.
Documentation
Development
Open this folder in VS Code and press F5 to launch an Extension Development Host.
node --check src/support.js
node --check src/mcpClient.js
node --check src/extension.js
node --test test/*.test.js
node test/runExtensionHost.js
