How does vite-plugin-page-annotator connect with Claude Code and OpenAI Codex?

It connects in three ways: (1) The page-annotator-inbox Claude Code plugin automatically fills the Claude Code prompt box whenever you click Send in the browser; (2) The built-in page-annotator-mcp stdio MCP server lets both Claude Code and OpenAI Codex fetch pending annotations and element screenshots via get_page_annotations and mark them resolved via mark_annotations_done; (3) One-click clipboard copy for pasting into any AI chat or terminal.

Does vite-plugin-page-annotator affect production builds?

No. Both the JSX source-location transform and the in-page Shadow DOM UI use apply: 'serve', meaning they only run during vite dev. A production vite build contains zero code or attributes from this plugin.

Which frontend frameworks are supported?

Any JSX/TSX framework (React, Preact, Solid, Qwik) gets exact file:line:column source locations powered by Vite's native parseAst. Non-JSX frameworks (Vue, Svelte, plain HTML) also work out of the box using automatic CSS selectors.

VITE DEV PLUGIN · CLAUDE CODE & CODEX

Point at the page. Let Claude Code or Codex fix it.

Click any element on your live Vite dev page and write what should change. Each annotation captures its exact JSX source location (file:line:column) and an optional screenshot, streaming straight to Claude Code or OpenAI Codex.

Configure →

Paste into Claude Code, Codex, or Cursor. Your agent installs the package, updates vite.config, and configures MCP automatically.

npm i -D vite-plugin-page-annotator

Claude & Codex integration → Manual setup → GitHub ↗

localhost:5173 vite dev

Get started

src/Hero.tsx:42:9

Use the brand accent color and 8px radius

[x] ScreenshotEnter ↵

Annotate · 3 items · Send ↗

❯get_page_annotations() → 3 notes + screenshot loaded

●patch src/Hero.tsx:42:9

✓mark_annotations_done([1, 2, 3])

01 / AUTO-INTEGRATION

Copy to Your AI Agent

Paste this prompt into Claude Code, OpenAI Codex, or Cursor. Your agent will install the plugin, update vite.config, ignore .page-annotator/, and configure MCP for you.

Vite Plugin + .gitignore Claude Code MCP Claude Code Inbox Plugin Codex MCP Chinese UI (lang: 'zh')

Machine-readable specification for agents: llms.txt ↗

02 / AGENT BRIDGE

Seamless Hand-Off to Claude Code & Codex

Three ways to connect your browser preview to your coding agent—all backed by the same local .page-annotator/ queue.

Auto-fill the Claude Code prompt box on every Send

The page-annotator-inbox plugin watches .page-annotator/outbox.json. Clicking Send in the browser places the fix prompt directly into your active Claude Code input box—just press Enter.

claude plugin install page-annotator-inbox --marketplace shinelikeamillion/vite-plugin-page-annotator

Or inside a Claude Code session run /plugin install page-annotator-inbox --marketplace shinelikeamillion/vite-plugin-page-annotator, or test once without installing: claude --plugin-dir node_modules/vite-plugin-page-annotator/claude-plugin

Zero-dependency MCP server for Claude Code & OpenAI Codex

Configure page-annotator-mcp once, then tell your agent: "handle the page annotations".

Claude Code · .mcp.json

{
  "mcpServers": {
    "page-annotator": { "command": "npx", "args": ["page-annotator-mcp"] }
  }
}

OpenAI Codex · ~/.codex/config.toml

[mcp_servers.page-annotator]
command = "npx"
args = ["page-annotator-mcp", "--root", "/absolute/path/to/your/project"]

Tool	Description
`get_page_annotations`	Reads pending annotations (JSON + screenshots) and marks them delivered
`mark_annotations_done`	Marks resolved annotation IDs as done
`clear_page_annotations`	Empties the queue when explicitly requested

Paste anywhere

Clicking Send copies both the structured prompt (with file:line:column JSON) and the element screenshot. In a terminal, ⌘V pastes text and CtrlV pastes the image.

03 / ARCHITECTURE

Built for the UI Edit Loop

Replace vague descriptions with exact source coordinates and visual context.

Exact JSX Source Locations

Tags JSX/TSX elements with file:line:column via Vite's native AST parser so your agent opens the exact line immediately.

Element Screenshots

Captures a cropped snapshot of the element as it looks now, saved to .page-annotator/shots/ and passed to the agent.

Batch Dispatch

Queue multiple UI notes across the page, review or edit drafts, and send everything in a single structured prompt.

Status & History

Items move from pending → delivered → done. Inspect the latest 200 completed annotations with thumbnails in-page.

Custom Prompt Templates

Customize the fix prompt using {{count}}, {{ids}}, {{page}}, and {{json}} placeholders. English and Chinese built in.

Zero Production Footprint

Runs only during vite dev inside an isolated Shadow DOM. Production builds contain zero bytes from this plugin.

04 / INTERFACE

Isolated Shadow DOM UI

Shows up on first visit, hides with ⌘⇧2, and never leaks styles into your application.

Annotating an element on a Vite dev page with source location badge and note input — 01 · Point & Annotate

Hover to inspect file:line:column, click to add a note, or press ↑ / ↓ to traverse parent and child elements.

Drafts queue popover showing three queued UI annotations before sending — 02 · Drafts Queue

Review, edit, or remove queued annotations before sending the batch to Claude Code or Codex.

Settings panel showing language toggle, screenshot default, and custom fix prompt template — 03 · Settings & Prompt Template

Right-click ⠿ to switch between English and Chinese, toggle default screenshots, or edit the prompt template.

History panel showing pending, delivered, and completed page annotations with thumbnails — 04 · Resolution History

Track pending, delivered, and done items along with element screenshot thumbnails.

05 / MANUAL SETUP

Manual Installation in Two Minutes

Requires Vite 8+ and Node.js 20.19+. Works with any JSX framework for source locations, or CSS selectors on any page.

Install the dev dependency
```
npm i -D vite-plugin-page-annotator
```

Add to vite.config.ts

Place pageAnnotator() before your framework plugin in vite.config.ts, and add .page-annotator/ to .gitignore.

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { pageAnnotator } from 'vite-plugin-page-annotator';

export default defineConfig({
  plugins: [pageAnnotator(), react()], // pageAnnotator({ lang: 'zh' }) for Chinese
});

Show the toolbar

Run npm run dev, open your page, and press ⌘⇧2 (CtrlShift2 on Windows/Linux).
Annotate elements

⌘+click anywhere (or AltA) to start, then click an element. Write what should change and press Enter. Use ↑ ↓ to select parent or child elements.
Send to your agent

Click Send. Notes are written to .page-annotator/, pushed to the Claude Code inbox / MCP queue, and copied to your clipboard.

06 / KEYMAP

Keyboard Shortcuts

On Windows and Linux, use Ctrl where you see ⌘.

`⌘⇧2`	Show or hide the toolbar (remembered)
`⌘`+click · `AltA`	Start annotating
Right-click · `Esc`	Stop annotating
`↑` `↓`	Pick parent or child element (⌥↑ ⌥↓ when text box has content)
`Enter` · `⇧Enter`	Save note · new line
Drag ⠿	Move toolbar; double-click ⠿ to reset
Right-click ⠿	Settings: language, prompt template, screenshot default, history

07 / FAQ

Frequently Asked Questions

How does Page Annotator connect with Claude Code and OpenAI Codex?

Three ways: (1) The page-annotator-inbox Claude Code plugin watches .page-annotator/outbox.json and automatically fills your Claude Code terminal prompt box whenever you click Send; (2) The built-in page-annotator-mcp stdio server lets Claude Code and Codex call get_page_annotations and mark_annotations_done; (3) One-click clipboard copy.

Does this plugin affect production builds?

No. Both the JSX locator transform and the UI script use apply: 'serve'. A vite build output contains zero code or attributes from this plugin.

Which frameworks support file:line:column source locations?

Any JSX/TSX framework (React, Preact, Solid, Qwik) gets automatic data-loc attributes via Vite's native parseAst. Non-JSX apps (Vue, Svelte, HTML) fall back to CSS selectors automatically.

Will saving annotations trigger unwanted Vite page reloads?

No. The plugin adds **/.page-annotator/** to Vite's server.watch.ignored list so writing queue files and screenshots never reloads your page.

Point at the page. Let Claude Code or Codex fix it.

Copy to Your AI Agent

Seamless Hand-Off to Claude Code & Codex

Auto-fill the Claude Code prompt box on every Send

Zero-dependency MCP server for Claude Code & OpenAI Codex

Paste anywhere

Built for the UI Edit Loop

Exact JSX Source Locations

Element Screenshots

Batch Dispatch

Status & History

Custom Prompt Templates

Zero Production Footprint

Isolated Shadow DOM UI

01 · Point & Annotate

02 · Drafts Queue

03 · Settings & Prompt Template

04 · Resolution History

Manual Installation in Two Minutes

Install the dev dependency

Add to vite.config.ts

Show the toolbar

Annotate elements

Send to your agent

Keyboard Shortcuts

Frequently Asked Questions