# VS Code extension

The repowise VS Code extension brings your local index into the editor with health signals, refactoring CodeLens and branch risk, and adds the MCP server.

The Repowise extension brings the local index into your editor and registers
the Repowise MCP server with VS Code, so the same index serves both you and
your AI coding agent. It is a thin client over the local `repowise` CLI and
server: everything is computed on your machine and nothing about your code
leaves it through the extension.

> **Note**
>
> This extension drives the **local, self-hosted** server (the index under
> `.repowise/`). If you use the hosted platform and want your agent to reach the
> managed MCP endpoint instead, see [Connecting your IDE](https://docs.repowise.dev/hosted/connecting-ide);
> no local index required.

## Install

1. **Install the CLI**

   ```bash
   pip install repowise
   # or
   uv tool install repowise
   ```

   Python 3.11+ required. Verify with `repowise --version`.

2. **Install the extension**

   From the VS Code Marketplace (search **Repowise**, publisher `repowise-dev`),
   or from [Open VSX](https://open-vsx.org) for VS Code forks.

3. **Set up the repository**

   Open a repository and run **Repowise: Set Up This Repository** to build the
   index, or follow the **Get Started with Repowise** walkthrough.

   The extension activates only in trusted workspaces and does no work at startup
   beyond registering its commands. It discovers a running server from the
   lockfile under `.repowise/`, or offers to start one when you first need data.

## Know before you push

**Analyze Change Risk** (Source Control title bar, or the command palette)
scores your uncommitted work against its base branch and opens a panel with
the whole story of the change:

- A summary strip: how many files are affected downstream, how many usual
  companion files you haven't touched, and how many changed files have no
  associated test. Each chip jumps to its section.
- **Riskiest files in this change**: your changed files ranked by how risky
  history and structure say they are, so you review in the right order. Files
  that change unusually often are marked as hotspots.
- **Downstream of your changes**: the files that depend on what you edited.
- **Usually changes together**: companion files your history says belong to
  this change but are untouched. Advisory, not a rule.
- **Changed without a test**, and **suggested reviewers** with one-click copy
  for the PR description.

While you edit, a quiet co-change hint can appear in the status bar when the
files you're touching have a strong history of changing together with a file
you haven't opened. Dismissible per change set, never a popup, and tunable or
off in settings (`repowise.changeIntel.*`).

## What it surfaces

### Editor-native signals

- **Gutter heat**: a severity-tiered strip next to lines with findings in the
  visible editor.
- **File health in the status bar**: defect, maintainability, and performance
  scores for the active file. See [Code health](https://docs.repowise.dev/intelligence/code-health).
- **File explorer badges** on the worst-health files (threshold configurable).
- **Refactoring CodeLens** above symbols with a detected plan, including
  **Copy plan for agent**: the same payload the web
  [Refactoring](https://docs.repowise.dev/intelligence/refactoring) tab produces.
- **Hovers**: line 1 of a file shows its health scores, primary owner, and
  governing [decisions](https://docs.repowise.dev/intelligence/decisions). Hovering a symbol shows
  what kind of symbol it is, how many callers and callees it has, who owns
  the file, and the decisions that govern it, fetched only when you hover,
  then cached.
- **Diagnostics** (off by default): opt in to publish high-severity findings
  to the Problems panel (`repowise.diagnostics.enabled`). The quieter
  surfaces above carry the full detail either way.
- **Documentation drift** (on by default): open Markdown files show
  references the tree no longer has in the Problems panel, on the line to
  edit. See [Documentation drift](https://docs.repowise.dev/intelligence/doc-drift).

### Tree views

A single Repowise activity-bar container with a **Home** overview, a
**Findings** tree (health, hotspots, ownership, dead code), and a
**Refactoring** tree. All lazy: data is fetched on first expand and refreshed
only when the index moves.

### Dashboards

Editor-tab webviews rendered from the same shared visualization library the web
app uses (no duplicated components): **health overview**, **architecture map**,
**knowledge graph** (with node search, path finder, and community detail),
**refactoring plans**, **decision timeline**, and a **docs browser**.

## MCP for your AI agent

One install registers the Repowise MCP server with VS Code, so agent-mode
assistants query the index through the [task-shaped tools](https://docs.repowise.dev/mcp/overview)
instead of guessing from open files. For editors that read a config file, run
**Repowise: Configure MCP for this Workspace** to write `.vscode/mcp.json`.

### Language Model Tools for Copilot Chat

Alongside the MCP server, the extension registers six native VS Code Language
Model Tools through `vscode.lm.registerTool`. GitHub Copilot Chat in Agent
mode can call them directly, with no external server process in the path.

| Tool | Parameters | What it returns |
|---|---|---|
| `repowise_searchCodebase` | `query` (string), `limit` (optional number) | Hybrid semantic and full-text search over indexed wiki pages: ranked snippets and file targets. |
| `repowise_getFileHealth` | `filePath` (string) | Defect, maintainability, and performance scores for a file, plus active biomarker findings. |
| `repowise_getRefactoringPlans` | `filePath` (string) | Refactoring plans targeting symbols in the file, with effort bucket, confidence, and blast radius. |
| `repowise_getBranchRisk` | `base` (optional string) | Scores uncommitted changes or working HEAD against the base branch: risk percentile, review priority, risk drivers. |
| `repowise_getSymbolInfo` | `filePath` (string), `symbolName` (optional string) | Line bounds, primary owner, callers, callees, and governing decisions for indexed symbols. |
| `repowise_getFileDocs` | `filePath` (string) | The generated wiki page content for a file. |

All six are read-only, respect workspace boundary checks, and cap each payload
at 30,000 characters so a large result cannot flood the chat context. Turn the
set on or off with `repowise.agentTools.enabled`.

## Settings

| Setting | Default | Purpose |
|---|---|---|
| `repowise.server.autoStart` | `ask` | Start the local server automatically, ask first, or never |
| `repowise.server.port` | discover | Override the server port instead of using lockfile discovery |
| `repowise.cliPath` | PATH | Absolute path to the `repowise` executable |
| `repowise.agentTools.enabled` | `true` | Register the native Language Model Tools for Copilot Chat agent mode |
| `repowise.diagnostics.enabled` | `false` | Publish health findings to the Problems panel. Off by default; gutter, badges, and hovers still surface findings |
| `repowise.diagnostics.minSeverity` | `high` | Lowest severity surfaced in the Problems panel |
| `repowise.diagnostics.dimensions` | all | Health dimensions included in the Problems panel |
| `repowise.docDrift.diagnostics.enabled` | `true` | Show documentation drift for open Markdown files in the Problems panel |
| `repowise.docDrift.diagnostics.minConfidence` | `0.7` | Lowest drift confidence shown |
| `repowise.gutterHeat.enabled` | `true` | Shade the gutter next to findings |
| `repowise.fileDecorations.enabled` | `true` | Badge the worst-health files in the explorer |
| `repowise.fileDecorations.maxScore` | `4` | Health score at or below which a file is badged |
| `repowise.codeLens.enabled` | `true` | Show refactoring plan lenses |
| `repowise.hover.enabled` | `true` | Show file health context on hover |
| `repowise.hover.symbolDetail` | `true` | Enrich symbol hovers with callers, callees, ownership, and decisions |
| `repowise.risk.baseBranch` | default branch | Base branch for branch risk scoring |
| `repowise.changeIntel.cochangeNudge` | `true` | Show the quiet "usually change together" status-bar hint |
| `repowise.changeIntel.cochangeMinScore` | `4` | Minimum historical co-change count before a related file is surfaced |

## Privacy

The extension talks only to the local Repowise CLI and server on your machine
and reads the index under `.repowise/`. It sends no telemetry of its own. The
CLI's own telemetry opt-out is respected because the extension itself sends
nothing.

## Learn more

- [Quickstart](https://docs.repowise.dev/getting-started/quickstart): install the CLI and build
  your first index.
- [The MCP tools](https://docs.repowise.dev/mcp/overview): what your agent can ask for.
- [Connecting your IDE](https://docs.repowise.dev/hosted/connecting-ide): the hosted MCP endpoint
  for other editors.
