Vibe Annotations is an AI-native visual feedback tool for your web apps. Ask changes, make design tweaks to your pages and share the structured output to your AI coding agent or teammates.
Get started: Install the browser extension
🧐 Is it for me? If you're a PM, Marketer, Designer or Developer having to review websites regularly, and looking for an efficient way to convey intent and share context with AI coding agents, then Vibe Annotations is made for you.
Vibe Annotations can be used to request changes on a website's look & copy without design or development knowledge. Learn more in the examples below.
✏️ Annotate, copy/paste to your AI coding agent:
clipboard_demo.mp4
🎨 Make persisting direct design tweaks:
design_edit_demo.mp4
🔌 Use the MCP server to share your annotations, any websites, multiple pages:
mcp_basic_demo.mp4
🤖 Annotate with a browser-capable AI coding agent:
annotate_with_agent_demo.mp4
Pro tip: This is using Claude browser extension, with a shortcut added (Settings>Shortcut) to trigger vibe window.__vibeAnnotations.help() when typing /vibe on first prompt.
🤝 Collaborate with teammates using export / import features:
multiplayer_demo.mp4
👀 Use watch mode, never leave your website:
watch_mode_demo.mp4
From Chrome Web Store: Install from the Chrome Web Store
For Development: Go to your chromium browser extension page, and click "Load unpacked" then select /extension directory.
npm install -g vibe-annotations-servervibe-annotations-server startChoose your AI coding agent and follow the setup:
In your project directory:
# Recommended (HTTP transport - more stable)
claude mcp add --transport http vibe-annotations http://127.0.0.1:3846/mcp
# Alternative (SSE transport - for compatibility)
claude mcp add --transport sse vibe-annotations http://127.0.0.1:3846/sse- Open Cursor → Settings → Cursor Settings
- Go to the Tools & Integrations tab
- Click + Add new global MCP server
- Add this configuration:
{
"mcpServers": {
"vibe-annotations": {
"url": "http://127.0.0.1:3846/mcp"
}
}
}Alternative (SSE transport):
{
"mcpServers": {
"vibe-annotations": {
"url": "http://127.0.0.1:3846/sse"
}
}
}- Navigate to Windsurf → Settings → Advanced Settings
- Scroll down to the Cascade section
- Add this configuration:
{
"mcpServers": {
"vibe-annotations": {
"serverUrl": "http://127.0.0.1:3846/mcp"
}
}
}Alternative (SSE transport):
{
"mcpServers": {
"vibe-annotations": {
"serverUrl": "http://127.0.0.1:3846/sse"
}
}
}Add to ~/.codex/config.toml:
[mcp_servers.vibe-annotations]
url = "http://127.0.0.1:3846/mcp"Add to ~/.openclaw/openclaw.json:
{
"mcpServers": {
"vibe-annotations": {
"url": "http://127.0.0.1:3846/mcp"
}
}
}Install an AI extension that supports MCP, then add this configuration to your MCP settings:
{
"mcpServers": {
"vibe-annotations": {
"url": "http://127.0.0.1:3846/mcp"
}
}
}Open a localhost page, click Annotate in the toolbar, and click any element to leave feedback. Then either:
- Copy & paste: Click Copy in the toolbar and paste into any AI chat
- MCP (automatic): Tell your agent to read and implement vibe annotations
- Watch mode (hands-free): Tell your agent "Start watching Vibe Annotations" — it loops automatically
To annotate local HTML files (file:// URLs) instead of localhost:
- Go to
chrome://extensions/ - Find "Vibe Annotations" and click "Details"
- Enable "Allow access to file URLs"
- Refresh your local HTML file
Note: This is only needed for local files. Localhost development servers work without this step.
Vibe Annotations is split into two independent pieces that talk over HTTP:
-
Browser Extension (
/extension) — Injects a floating toolbar on any page. Handles inspection mode, annotation popovers, live CSS previews, badge rendering, import/export, and clipboard copy. Stores annotations in Chrome Storage and syncs them to the server when available. -
MCP Server (
vibe-annotations-server) — A global npm package that runs locally. Exposes an HTTP API for the extension and MCP endpoints for AI coding agents. Stores annotations as JSON on disk. Agents connect via MCP to read, watch, and delete annotations.
┌─────────────────┐ HTTP ┌─────────────────┐ MCP
│ │ ←── sync/CRUD ───→ │ │ ←── tools ───→ AI Agents
│ Browser Extension │ │ MCP Server │ (Claude Code,
│ (Chrome) │ │ (port 3846) │ Cursor, etc.)
└─────────────────┘ └─────────────────┘
The extension works standalone (copy/paste, export) but the server unlocks MCP integration and watch mode.
The server exposes these tools to connected agents:
| Tool | Description |
|---|---|
read_annotations |
Retrieve pending annotations with URL filtering and pagination |
watch_annotations |
Long-poll for new annotations (used in watch mode loops) |
delete_annotation |
Remove an annotation after implementing the fix |
delete_project_annotations |
Batch delete all annotations for a project URL |
get_project_context |
Infer framework and tech stack from a localhost URL |
get_annotation_screenshot |
Get screenshot data for visual context |
# Check server status
vibe-annotations-server status
# Stop server
vibe-annotations-server stop
# Restart server
vibe-annotations-server restartTo completely remove Vibe Annotations from your system:
claude mcp remove vibe-annotationsGo to Cursor → Settings → Cursor Settings → Tools & Integrations tab and remove the vibe-annotations server configuration.
Go to Windsurf → Settings → Advanced Settings → Cascade section and remove the vibe-annotations server from your MCP configuration.
Remove the vibe-annotations server from your editor's MCP configuration settings.
npm uninstall -g vibe-annotations-serverrm -rf ~/.vibe-annotationsGo to Chrome Extensions (chrome://extensions/) and remove the Vibe Annotations extension.
If you're developing Vibe Annotations or prefer to run the server locally instead of the global installation:
# Clone the repository
git clone https://github.com/RaphaelRegnier/vibe-annotations.git
cd vibe-annotations/annotations-server
# Install dependencies
npm install
# Run the server locally
npm run start
# or for development with auto-restart:
npm run devSee /extension directory for browser extension development. Load the extension in Chrome as unpacked extension.
- Update System - Comprehensive guide to extension and server update notifications
- Development Guide - Development setup and guidelines
Having issues? Check our GitHub Issues or create a new one.
- Server not detected: Make sure the server is running with
vibe-annotations-server status - Extension not working on public URLs: The extension works on any URL, but MCP server features (auto-sync, watch mode) require localhost. On public sites, use copy/paste or export
- MCP connection failed: Verify your AI coding agent configuration matches the examples above
- SSE connection drops/timeouts: If experiencing "TypeError: terminated" or frequent disconnections, switch to HTTP transport (replace
/ssewith/mcpin your configuration)
We love contributions! Please see our Contributing Guidelines for details.
Thanks to everyone who has contributed to making Vibe Annotations better!
PolyForm Shield 1.0.0 — see LICENSE and NOTICE for details. Versions prior to v1.5.0 were released under MIT.