Vibe Annotations

🌐 Website: https://www.vibe-annotations.com/

AI-powered development annotations for local development projects. Drop comments on your local development apps and let your AI coding agent implement the fixes automatically.

https://github.com/user-attachments/assets/4c134852-090b-4974-85e5-be77a95636f9

How it Works

1. Open your localhost app and click "Annotate" in the floating toolbar

2. Click any element — a popover appears to leave your feedback

3. Your AI agent fetches annotations automatically via MCP, or you can copy them to clipboard with full element context

4. Settings: MCP server status, clear-after-copy, screenshots, theme toggle

5. AI agent implements fixes and deletes annotations via MCP — all from your browser

Features

• 🏠 Local development focused: Works on localhost, .local, .test, .localhost domains
• 📑 Multi-page annotations: Create feedback across multiple routes in your app, then bulk-process all annotations at once for efficient fixes
• 🤖 AI-powered: Integrates with AI coding agents via MCP
• ⚡ Instant feedback: Click, comment, bulk-fix
• 👨‍💻 Developer-friendly: Built for modern web development

Architecture

Vibe Annotations uses a two-piece architecture:

1. Browser Extension (/extension): UI, setup guidance, annotation management
2. NPM Package (vibe-annotations-server): MCP server, local HTTP API, data storage

Quick Start

1. Install the Browser Extension

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.

2. Install the Global Server

npm install -g vibe-annotations-server

3. Start the Server

vibe-annotations-server start

4. Connect Your AI Coding Agent

Choose your AI coding agent and follow the setup:

Claude Code

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

Cursor

1. Open Cursor → Settings → Cursor Settings
2. Go to the Tools & Integrations tab
3. Click + Add new global MCP server
4. 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"
    }
  }
}

Windsurf

1. Navigate to Windsurf → Settings → Advanced Settings
2. Scroll down to the Cascade section
3. 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"
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.vibe-annotations]
url = "http://127.0.0.1:3846/mcp"

OpenClaw

Add to ~/.openclaw/openclaw.json:

{
  "mcpServers": {
    "vibe-annotations": {
      "url": "http://127.0.0.1:3846/mcp"
    }
  }
}

VS Code

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"
    }
  }
}

5. Start Using Annotations

• Open the extension popup for detailed setup instructions
• Start annotating your local development projects!
• Use your AI coding agent to automatically implement fixes

6. (Optional) Enable Local File Support

To annotate local HTML files (file:// URLs) instead of localhost:

1. Go to chrome://extensions/
2. Find "Vibe Annotations" and click "Details"
3. Enable "Allow access to file URLs"
4. Refresh your local HTML file

Note: This is only needed for local files. Localhost development servers work without this step.

User Experience Flow

1. Extension Installation: Install from Chrome Web Store
2. Setup Instructions: Extension popup guides through terminal setup
3. Server Detection: Extension automatically detects running server
4. Daily Usage: Create annotations → Use your AI coding agent → Fixes implemented

Server Management

# Check server status
vibe-annotations-server status

# Stop server
vibe-annotations-server stop

# Restart server
vibe-annotations-server restart

Uninstallation

To completely remove Vibe Annotations from your system:

1. Remove MCP Server from Your AI Coding Agent

Claude Code

claude mcp remove vibe-annotations

Cursor

Go to Cursor → Settings → Cursor Settings → Tools & Integrations tab and remove the vibe-annotations server configuration.

Windsurf

Go to Windsurf → Settings → Advanced Settings → Cascade section and remove the vibe-annotations server from your MCP configuration.

Other Editors

Remove the vibe-annotations server from your editor's MCP configuration settings.

2. Uninstall the Global Server

npm uninstall -g vibe-annotations-server

3. Remove Data Files

rm -rf ~/.vibe-annotations

4. Remove Browser Extension

Go to Chrome Extensions (chrome://extensions/) and remove the Vibe Annotations extension.

Development

Local Server Development (Advanced)

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 dev

Note: Running locally ties the server to this specific directory. Most users should use the global installation method shown above.

Extension Development

See /extension directory for browser extension development. Load the extension in Chrome as unpacked extension.

Documentation

• Update System - Comprehensive guide to extension and server update notifications
• Development Guide - Development setup and guidelines

Troubleshooting

Having issues? Check our GitHub Issues or create a new one.

Common Issues

• Server not detected: Make sure the server is running with vibe-annotations-server status
• Extension not working: Check that you're on a local development URL (localhost, 127.0.0.1, 0.0.0.0, *.local, *.test, *.localhost)
• 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 /sse with /mcp in your configuration)

Contributing

We love contributions! Please see our Contributing Guidelines for details.

Contributors

Thanks to everyone who has contributed to making Vibe Annotations better!

License

PolyForm Shield 1.0.0 — see LICENSE and NOTICE for details. Versions prior to v1.5.0 were released under MIT.