vite-plugin-ai-annotator

AI-powered element annotator for Vite - Pick elements and get instant AI code modifications.

📺 Watch the Tutorial Video - See the plugin in action!

What is this?

Point at any element on your webapp, type a request, and AI modifies your code instantly.

• Point directly at any element on your webapp
• Type a short request like "make it bigger", "center it", "change color to blue"
• Wait for AI to modify your code - it automatically finds and updates the source files
• See instant results - your changes appear immediately in the browser

Save cognitive load, because it's precious.

Why use it?

Traditional workflow: inspect element → find source file → locate the code → make changes → check results.

With this plugin: point → describe → done.

Works with all Vite-supported frameworks:

• ⚛️ React - Detects components, props, and state
• 🟢 Vue - Understands composition/options API
• 🅰️ Angular - Recognizes components and directives
• 🟠 Svelte - Identifies components and stores
• 📄 Vanilla JS - Works with plain HTML/CSS/JS
• 🟦 Nuxt.js - Full support via Nuxt module (Nuxt 4+)

Installation

Option 1: Automatic Setup (Recommended)

Install the Claude Code plugin and let AI set everything up for you:

/plugin marketplace add nguyenvanduocit/claude-annotator-plugin
/plugin install claude-annotator-plugin@claude-annotator-plugin

Then ask Claude: "Set up ai-annotator for my project" - it handles the rest!

Option 2: Manual Setup

For Vite Projects

Step 1: Install the package

bun add -d vite-plugin-ai-annotator

Step 2: Add to your Vite config

import { defineConfig } from 'vite';
import annotator from 'vite-plugin-ai-annotator';

export default defineConfig({
  plugins: [
    annotator(),
  ],
});

For Nuxt.js Projects (Nuxt 4+)

Step 1: Install the package

bun add -d vite-plugin-ai-annotator

Step 2: Add to your nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'vite-plugin-ai-annotator/nuxt'
  ],
  // Optional: Configure the annotator
  aiAnnotator: {
    port: 7318,
    autoSetupMcp: true,
    verbose: false,
  }
})

That's it! Nuxt handles the rest automatically.

Configure MCP (Vite and Nuxt)

Option A: Auto Setup (Recommended)

Enable automatic MCP configuration in your Vite config:

annotator({
  autoSetupMcp: true,
})

For Nuxt, configure in nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['vite-plugin-ai-annotator/nuxt'],
  aiAnnotator: {
    autoSetupMcp: true,
  }
})

This automatically creates/updates .mcp.json, .cursor/mcp.json, and .vscode/mcp.json based on your project.

Option B: Manual Setup

claude mcp add annotator -- npx vite-plugin-ai-annotator mcp -s http://localhost:7318

Step 3: Start your dev server

bun dev

The annotator toolbar will automatically appear in your application.

Usage

1. Click the inspect button on the toolbar to enter feedback mode
2. Click on any element(s) you want to provide feedback on
3. Ask Claude Code to modify them - it will use annotator_get_feedback to get the selected feedback with their source locations
4. Claude modifies the source code directly

Example prompt: "Make the selected button larger and change its color to blue"

Configuration

annotator({
  port: 7318,              // Server port (default: 7318)
  autoSetupMcp: true,      // Auto-configure MCP files (default: false)
  autoSetupSkills: true,   // Auto-write AI tool skill files (default: true)
  verbose: false,          // Enable detailed logging (default: false)
})

Auto MCP Setup

When autoSetupMcp: true, the plugin automatically:

1. Detects your package manager from lockfile:

   • bun.lockb / bun.lock → uses bunx
   • pnpm-lock.yaml → uses pnpm dlx
   • Otherwise → uses npx

2. Creates/updates MCP config files:

   • .mcp.json - Claude Code, Cline, Roo Code
   • .cursor/mcp.json - Cursor (only if .cursor/ exists)
   • .vscode/mcp.json - VS Code (only if .vscode/ exists)

3. Preserves existing config - merges with other MCP servers, doesn't overwrite

Auto AI Skills Setup

When autoSetupSkills: true (default), the plugin writes skill/instruction files on every dev server start with the correct server address baked in. This means AI tools automatically know how to call the REST API:

| AI Tool | File | Format | |---------|------|--------| | Claude Code | .claude/skills/ai-annotator/SKILL.md | YAML frontmatter (name, description) | | Cursor | .cursor/rules/ai-annotator.mdc | alwaysApply: true | | Windsurf | .windsurf/rules/ai-annotator.md | trigger: always_on | | Codex | AGENTS.md | Marker-delimited section | | Copilot | .github/instructions/ai-annotator.instructions.md | applyTo: "**" | | Cline | .clinerules/ai-annotator.md | Plain markdown |

Files are updated on every server restart, so the address is always correct.

REST API

The server exposes a plain HTTP REST API at /api/*, usable by any HTTP client — no MCP required.

# List sessions
curl http://localhost:7318/api/sessions

# Get feedback
curl http://localhost:7318/api/sessions/<id>/feedback

# Inject JS
curl -X POST http://localhost:7318/api/sessions/<id>/inject-js \
  -H 'Content-Type: application/json' \
  -d '{"code": "document.title"}'

| Method | Endpoint | Body/Query | Description | |--------|----------|------------|-------------| | GET | /api/sessions | — | List connected browser sessions | | GET | /api/sessions/:id/page-context | — | Page URL, title, selection count | | POST | /api/sessions/:id/select | {mode?, selector?, selectorType?} | Trigger feedback selection | | GET | /api/sessions/:id/feedback | ?fields=xpath,attributes,styles,children | Get selected feedback items | | DELETE | /api/sessions/:id/feedback | — | Clear all selections | | POST | /api/sessions/:id/screenshot | {type?, selector?, quality?} | Capture screenshot | | POST | /api/sessions/:id/inject-css | {css} | Inject CSS into page | | POST | /api/sessions/:id/inject-js | {code} | Execute JS in page context | | GET | /api/sessions/:id/console | ?clear=true | Get captured console logs |

Happy coding! 🚀