AI Eye

AI-native visual development for VS Code Bridge the gap between UI and code with live preview, source mapping, and AI agent integration

What is AI Eye?

AI Eye is an AI-native visual development extension for VS Code that enables both human developers and AI agents to:

👁️ See your UI - Live preview panel embedded in VS Code
🎯 Navigate visually - Click elements → jump to source code
🤖 Enable AI agents - Let AI see, inspect, and interact with your UI
🔍 Debug faster - Visual inspection with source mapping
⚡ Track HMR - Real-time Hot Module Replacement status

Perfect for:

Visual debugging and development
AI-assisted coding with tools like Claude Code
Understanding unfamiliar codebases
Rapid prototyping and iteration
Teaching and pair programming

✨ Features

🆕 v2: Embedded Webview Architecture (NEW!)

Lightning-fast AI agent integration:

⚡ Instant startup - No browser launch delay
💾 90% less memory - Uses only 20MB vs 200MB
🚀 75% faster - Sub-50ms response times
🎯 Seamless UX - Everything in VS Code
🔧 Zero config - Works out of the box

Technical highlights:

Embedded MCP server runs in extension host
Direct postMessage communication (no STDIO overhead)
All 14 tools fully functional
Backward compatible with v1

For Human Developers

Live Preview

Embedded browser preview in VS Code
Click any element to jump to its source code
Real-time HMR updates
Interactive debugging

Source Mapping

Every UI element traces back to source code
See exact file, line, and column for each element
Works with React, Vue, Svelte

Visual Debugging

Console logs captured in VS Code
Element inspection with computed styles
Bounding boxes and layout information

For AI Agents

AI Eye provides 14 MCP tools for AI agents (Claude, Copilot, etc.):

aieye_screenshot - Capture page screenshots
aieye_inspect_element - Get element details + source location
aieye_get_source - Find where code is defined
aieye_get_structure - Get component hierarchy
aieye_find_elements - Search by text/role/selector
aieye_click - Interact with buttons
aieye_type - Fill forms
aieye_scroll - Access elements below fold
aieye_get_console_logs - Debug errors
aieye_get_hmr_status - Check build status
...and 4 more

See docs/AI-USAGE.md for complete AI agent guide.

🚀 Quick Start

For Users

1. Install the VS Code Extension

(Coming soon to VS Code Marketplace)

For now, install from source:

git clone https://github.com/SPra03/ai-eye.git
cd ai-eye
npm install -g pnpm  # or use: npx pnpm
pnpm install
pnpm build

Open in VS Code and press F5 to launch Extension Development Host.

2. Install Plugin in Your Project

For Vite projects (React, Vue, Svelte):

npm install @ai-eye/vite-plugin --save-dev

// vite.config.ts
import aiEye from '@ai-eye/vite-plugin';

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

For Create React App:

npm install @ai-eye/babel-plugin react-app-rewired customize-cra --save-dev

See docs/GETTING-STARTED.md for detailed setup.

3. Start Your Dev Server

npm run dev
# Dev server running at http://localhost:5173

4. Open AI Eye Preview

In VS Code:

Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
Type: "AI Eye: Open Live Preview"
Click elements to navigate to source code!

For AI Agents

1. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aieye": {
      "command": "node",
      "args": ["/path/to/ai-eye/packages/mcp-server/dist/index.js"],
      "env": {
        "AIEYE_URL": "http://localhost:5173"
      }
    }
  }
}

2. Use AI Eye Tools

You: "Take a screenshot of my app and tell me what you see"

Claude: [Uses aieye_screenshot]
        "I can see a login form with two input fields and a submit button.
         The button is defined at src/LoginForm.tsx:45.
         Would you like me to inspect it further?"

See docs/AI-USAGE.md for comprehensive guide.

📖 Documentation

Getting Started

Installation Guide - Setup instructions
Tool Reference - Quick reference cheat sheet
Examples - Example projects

For Developers

API Reference - Complete API documentation
Contributing - Development guidelines
Changelog - Version history

For AI Agents

AI Usage Guide - Complete guide for AI agents
Tool Reference - 14 MCP tools explained
Troubleshooting - Common issues

Package Documentation

@ai-eye/extension - VS Code extension
aieye - MCP server
@ai-eye/vite-plugin - Vite plugin
@ai-eye/babel-plugin - Babel plugin
@ai-eye/bridge - Browser bridge

🎯 Use Cases

Visual Debugging

Before AI Eye:

1. See bug in browser
2. Search codebase for component
3. Guess which file it's in
4. Open multiple files
5. Find the right element

With AI Eye:

1. See bug in AI Eye preview
2. Click element
3. VS Code opens exact file and line
4. Fix bug
5. See update instantly

AI-Assisted Development

Example workflow:

User: "The login button doesn't look right"

AI: [Takes screenshot]
    [Inspects button element]
    "I can see the button at src/Login.tsx:45.
     It has incorrect padding. Let me fix it..."
    [Edits file]
    [Takes new screenshot]
    "Fixed! The button now has proper spacing."

Component Exploration

Navigate unfamiliar codebases visually:

Open preview of the app
Click around to explore components
Understand component hierarchy visually
Jump to relevant source files

🏗️ Architecture

AI Eye has two modes: v1 (External Browser) and v2 (Embedded Webview).

v2 Architecture (Recommended - Faster & Integrated)

┌─────────────────────────────────────────────────────────┐
│           VS Code                                       │
│  ┌──────────────────────────────────────────────────┐   │
│  │  AI Eye Extension                           │   │
│  │  ┌────────────────┐  ┌────────────────────────┐  │   │
│  │  │  Webview       │  │  Embedded MCP Server   │  │   │
│  │  │  Bridge        │←→│  (Extension Host)      │  │   │
│  │  └────────┬───────┘  └───────────▲────────────┘  │   │
│  │           │                      │                │   │
│  │  ┌────────▼──────────────────────┼──────────┐    │   │
│  │  │  Webview Panel (iframe)       │          │    │   │
│  │  │  ┌────────────────────────────┼────────┐ │    │   │
│  │  │  │  Your App                  │        │ │    │   │
│  │  │  │  + AI Eye Bridge      │        │ │    │   │
│  │  │  │    (postMessage protocol)  │        │ │    │   │
│  │  │  └────────────────────────────┼────────┘ │    │   │
│  │  └───────────────────────────────┘          │    │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────────────┬───────────────────────────┘
                               │
                               ↓
                     AI Agent (Claude Code, etc.)

Benefits:

⚡ Instant startup (no browser launch)
💾 90% less memory (20MB vs 200MB)
🚀 75% faster (20-50ms vs 100-200ms latency)
🎯 Integrated UX (everything in VS Code)

v1 Architecture (Legacy - External Browser)

┌─────────────────────────────────────────┐
│           VS Code                       │
│  ┌──────────────────────────────────┐   │
│  │  AI Eye Extension           │   │
│  │  - Live Preview Panel            │   │
│  │  - Source Navigation             │   │
│  └──────────────────────────────────┘   │
└────────────┬────────────────────────────┘
             │
             ↓
┌────────────┴────────────────────────────┐
│        MCP Server                       │
│  - 14 AI Agent Tools                    │
│  - Browser Automation (Playwright/CDP)  │
└────────────┬────────────────────────────┘
             │
             ↓
┌────────────┴────────────────────────────┐
│    External Chromium Browser            │
│  ┌──────────────────────────────────┐   │
│  │  Your App                        │   │
│  │  + AI Eye Bridge            │   │
│  │    (injected by plugin)          │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘

Use v1 when:

Need full Playwright/CDP capabilities
Debugging cross-browser issues
Advanced automation scenarios

Core Components

VS Code Extension - Live preview panel and commands
Embedded MCP Server (v2) - Runs in extension host, zero overhead
External MCP Server (v1) - Separate process with browser automation
Webview Bridge (v2) - High-level API for webview interactions
Vite Plugin - Injects source mapping for Vite projects
Babel Plugin - Injects source mapping for Babel projects
Browser Bridge - Runs in browser, provides inspection API

🎓 Examples

React + Vite

Complete example with full source mapping:

cd examples/react-vite-app
npm install
npm run dev

Then open AI Eye preview and click around!

Test Preview

Simple HTML test page for quick verification:

cd examples/test-preview
node server.js

See examples/README.md for more examples and framework guides.

🛠️ Development

Setup

# Clone repository
git clone https://github.com/SPra03/ai-eye.git
cd ai-eye

# Install dependencies
npm install -g pnpm  # or use: npx pnpm
pnpm install

# Build all packages
pnpm build

# Watch mode for development
pnpm dev

Running Tests

# Run all tests
pnpm test

# Run specific package tests
pnpm --filter @ai-eye/vite-plugin test
pnpm --filter @ai-eye/babel-plugin test
pnpm --filter @ai-eye/bridge test

Project Structure

ai-eye/
├── packages/
│   ├── extension/        # VS Code extension
│   ├── mcp-server/      # MCP server for AI agents
│   ├── babel-plugin/    # Babel source mapping plugin
│   ├── vite-plugin/     # Vite source mapping plugin
│   └── bridge/          # Browser bridge script
├── examples/
│   ├── react-vite-app/  # React + Vite example
│   └── test-preview/    # Simple test server
├── docs/                # Documentation
└── scripts/             # Build and publish scripts

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Ways to contribute:

Report bugs and request features via GitHub Issues
Improve documentation
Add new framework examples
Submit pull requests

Development workflow:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

🔧 Configuration

VS Code Extension Settings

Setting	Description	Default
`aieye.devServerUrl`	Dev server URL	`http://localhost:5175`
`aieye.framework`	Framework detection	`auto`
`aieye.screenshotQuality`	Screenshot quality (30-100)	`80`
`aieye.enableCDP`	Enable CDP mode (v1 only)	`false`

Note: v2 uses the embedded webview by default. v1 (external browser) is still available for advanced use cases.

Vite Plugin Options

aiEye({
  enabled: true,              // Enable source mapping
  enableHMR: true,           // Track HMR updates
  root: __dirname,           // Project root
  include: /\.(jsx|tsx|vue|svelte)$/,  // Files to process
  exclude: /node_modules/,   // Files to exclude
  attributePrefix: 'data-ae' // Attribute prefix
})

MCP Server Environment Variables

AIEYE_URL=http://localhost:5173  # Dev server URL
AIEYE_MODE=playwright-launch     # Connection mode

See docs/GETTING-STARTED.md for complete configuration guide.

📊 Supported Frameworks

Framework	Support	Plugin
React (Vite)	✅ Full	Vite Plugin
Vue 3 (Vite)	✅ Full	Vite Plugin
Svelte (Vite)	✅ Full	Vite Plugin
React (CRA)	✅ Full	Babel Plugin
Next.js	⚠️ Experimental	Babel Plugin
Angular	❌ Not yet	-
Plain HTML	✅ Supported	None needed

See docs/GETTING-STARTED.md for framework-specific setup.

⚠️ Troubleshooting

Common Issues

"Source mapping not working" → Ensure plugin is installed and dev server restarted → See docs/TROUBLESHOOTING.md#source-mapping-issues

"Not connected to browser" → Check dev server is running → Verify URL in settings → See docs/TROUBLESHOOTING.md#mcp-server-issues

"Element not found" → Use aieye_find_elements to search → Take screenshot to see what's actually there → See docs/TROUBLESHOOTING.md#error-messages-explained

See docs/TROUBLESHOOTING.md for complete troubleshooting guide.

🎯 Roadmap

v1.0 (Released)

✅ Core functionality
✅ VS Code extension
✅ External MCP server with 14 tools
✅ Vite and Babel plugins
✅ Comprehensive documentation
✅ Example projects
✅ Test coverage (90+ tests)

v2.0 (Current - Just Released!)

✅ Embedded MCP Server - Runs in extension host
✅ Webview Integration - Direct VS Code webview support
✅ postMessage Protocol - Cross-origin communication
✅ 90% Memory Reduction - 20MB vs 200MB
✅ 75% Faster - Sub-50ms latency
✅ All 14 Tools Working - Full compatibility
✅ Automated Test Suite - 10/10 tests passing
✅ Comprehensive Documentation - V2-IMPLEMENTATION-SUMMARY.md

v2.1 (Next - In Progress)

v2.2 (Planned)

VS Code Marketplace publication
NPM package publication
Additional framework support (Angular, Solid)
Multi-webview support

v3.0 (Future)

Multi-page application support
Mobile device preview
Collaborative debugging
Plugin ecosystem

See CHANGELOG.md for version history.

📜 License

See LICENSE for details.

🙏 Acknowledgments

AI Eye builds on amazing open-source projects:

📞 Support & Community

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions

🌟 Star History

If you find AI Eye useful, please consider giving it a star on GitHub! ⭐

Built with ❤️ for visual developers and AI agents

Get Started · Documentation · Examples · Contributing

aieye

Quick Install

AI Eye

What is AI Eye?

✨ Features

🆕 v2: Embedded Webview Architecture (NEW!)

For Human Developers

For AI Agents

🚀 Quick Start

For Users

For AI Agents

📖 Documentation

Getting Started

For Developers

For AI Agents

Package Documentation

🎯 Use Cases

Visual Debugging

AI-Assisted Development

Component Exploration

🏗️ Architecture

v2 Architecture (Recommended - Faster & Integrated)

v1 Architecture (Legacy - External Browser)

Core Components

🎓 Examples

React + Vite

Test Preview

🛠️ Development

Setup

Running Tests

Project Structure

🤝 Contributing

🔧 Configuration

VS Code Extension Settings

Vite Plugin Options

MCP Server Environment Variables

📊 Supported Frameworks

⚠️ Troubleshooting

Common Issues

🎯 Roadmap

v1.0 (Released)

v2.0 (Current - Just Released!)

v2.1 (Next - In Progress)

v2.2 (Planned)

v3.0 (Future)

📜 License

🙏 Acknowledgments

📞 Support & Community

🌟 Star History

Reviews