<div align="center">

# Explain Changes

**AI peer review for your code changes.**

Just like humans review each other's PRs, your AI reviews its own changes — with inline annotations that appear directly in a VS Code/Cursor panel.

![Screenshot](assets/screenshot.png)

</div>

---

## Why AI Peer Review?

When humans write code, we do peer review. When AI writes code, we... scroll through chat hoping we understood what it did?

**The asymmetry is broken.** AI generates multi-file changes in seconds, but understanding those changes still requires you to:
- Read the chat explanation
- Open the diff
- Mentally map one to the other

This extension gives AI the same workflow humans use: **review the diff, annotate the changes, explain the reasoning**.

---

## How It Works

```
AI makes changes → AI reviews its own diff → Panel opens with annotated diff
```

The AI calls `show_diff_explanation` after completing a task. You get a visual diff with inline annotations — exactly where a human reviewer would leave comments.

Action buttons let you send improvement suggestions directly to Cursor chat.

---

## Features

- **Visual diff** — Side-by-side or unified view powered by diff2html
- **Inline annotations** — Review comments appear directly after relevant code lines
- **Action buttons** — Click to send prompts to Cursor chat ("Refactor this", "Add tests")
- **Click to open** — File names link directly to the source
- **Workspace-aware** — Only shows in the window matching your project
- **Auto-install MCP** — Extension configures the MCP server automatically

---

## Installation

### 1. Install the Extension

Download the `.vsix` from [releases](https://github.com/vltansky/explain-changes-mcp/releases) and install:

**VS Code / Cursor:**
- Extensions → `...` → "Install from VSIX..."

**The extension automatically configures the MCP server** in Cursor and Windsurf on first activation.

### 2. Use with AI

In Cursor chat, use the slash command:

```
/explain-changes
```

This triggers the MCP prompt which guides the AI to analyze your changes and call the tool automatically.

---

## Manual MCP Configuration

If auto-install doesn't work, configure manually:

<details>
<summary><b>Cursor</b></summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "explain-changes": {
      "command": "npx",
      "args": ["-y", "explain-changes-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "explain-changes": {
      "command": "npx",
      "args": ["-y", "explain-changes-mcp"]
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "explain-changes": {
      "command": "npx",
      "args": ["-y", "explain-changes-mcp"]
    }
  }
}
```

</details>

---

## Packages

| Package | Description |
|---------|-------------|
| [packages/extension](./packages/extension) | VS Code/Cursor extension that displays diff explanations |
| [packages/mcp](./packages/mcp) | MCP server with the `show_diff_explanation` tool |

---

## Architecture

```
┌─────────────────┐     writes JSON      ┌─────────────────┐
│   MCP Server    │ ──────────────────▶  │ ~/.explain-     │
│                 │                      │ changes/        │
│ show_diff_      │                      │ pending.json    │
│ explanation     │                      └────────┬────────┘
└─────────────────┘                               │
                                                  │ watches
                                                  ▼
                                         ┌─────────────────┐
                                         │  VS Code/Cursor │
                                         │   Extension     │
                                         │                 │
                                         │  Webview Panel  │
                                         └─────────────────┘
```

---

## Development

```bash
# Install dependencies
npm install

# Build all packages
npm run build

# Build extension only
npm run build:extension

# Build MCP only
npm run build:mcp

# Package extension as .vsix
cd packages/extension && npm run package
```

---

## License

MIT