visdiff

Give your coding agent visual feedback on your app.

Visdiff connects a running web page to the source code behind it. Adjust an element in the browser, capture the visual change, and give the resulting task to an agent through its CLI or MCP client.

Documentation: explore the Visdiff guide or read its source in docs/.

How it works

flowchart LR
    Browser["Running app<br/>Select · move · resize · layout"]
    Queue["Project task queue<br/>.visdiff/tasks.json"]
    Agent["Coding agent<br/>CLI or MCP"]
    Source["Source code<br/>Implement · verify"]

    Browser -->|"Apply visual task"| Queue
    Queue -->|"Read task + context"| Agent
    Agent -->|"Inspect and update"| Source
    Source -->|"Run checks and verify"| Agent
    Agent -->|"Clear applied task IDs"| Queue

Visdiff does not patch source code or make an agent guess from a screenshot alone. It captures the browser result and useful context; the agent inspects the source and chooses a maintainable implementation.

Quick start with Vite

Requirements: Node.js >=22.12.0.

npm install -D visdiff

Register the plugin before your framework plugin in the existing Vite configuration:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { visdiffVite } from 'visdiff/vite'

export default defineConfig({
  plugins: [visdiffVite(), react()],
})

Start your development server, open the app, and click visdiff to make and apply a visual task.

1. Click visdiff, then select an element.
2. Drag it, resize it, or use the arrow keys to move it. Shift + arrow moves it by 10 px.
3. Shift-click additional elements to create a multi-selection. If they share a parent, open Layout to preview Flex/Grid and alignment changes on that shared container.
4. Add an optional task note or per-change comment, then click Apply to enqueue the task.

Click Copy prompt instead of Apply to paste the task into any agent without the CLI or MCP. Edits collect in the change panel until applied. Reset restores the current preview; Esc or ✕ cancels the selection; Clear discards the unsent batch. Applied preview styles remain until the app's code or HMR replaces them.

Connect an agent

Run from the project root to read tasks and agent instructions:

npx -y visdiff tasks
npx -y visdiff instructions

Clear only the task IDs the agent implemented and verified:

npx -y visdiff clear <task-id> [task-id ...]

Or connect through MCP. For Claude Code:

claude mcp add visdiff -- npx -y visdiff mcp

Other MCP clients can launch npx -y visdiff mcp over local stdio. See the agent workflow for implementation and verification rules.

Framework and bundler support

Vite provides the integrated overlay, endpoint, and source anchors for React, Vue, and Svelte. visdiff/webpack supports these frameworks through Webpack; visdiff/next supports Next.js with Turbopack and webpack. See the support matrix for details. Integrations run in development only.

Development

npm run check
npm run build
npm run docs:build

npm run check runs ESLint, TypeScript checks, and package tests. CI runs unit tests on Node 22.12 and 24; lint, typecheck, builds, documentation, and browser tests run on Node 24.

License

MIT. See LICENSE.