🔍 Eyeglass

Visual debugging for AI coding agents. Point at UI elements in your browser and tell your AI assistant what to change—without leaving your browser.

Eyeglass bridges the gap between what you see in your browser and what your AI coding assistant can understand. Select any element, describe what you want, and your agent automatically receives the context it needs to make the change.

Supported agents: Claude Code, GitHub Copilot CLI, OpenAI Codex CLI

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     Browser     │     │     Bridge      │     │    AI Agent     │
│   (Inspector)   │────▶│  (MCP / HTTP)   │◀────│ Claude/Copilot/ │
└─────────────────┘     └─────────────────┘     │     Codex       │
        │                       │               └─────────────────┘
   1. Select element      2. Stores context             │
      + type request         + emits events       3. Polls for requests
        │                       │                       │
        └───────────────────────┴───────────────────────┘
                    4. Agent receives request,
                       makes changes, HMR updates browser

1. You select an element in your browser and type a request (e.g., "make this blue")
2. The Inspector captures semantic information: component name, file path, accessibility tree, styles
3. The Bridge stores this context and exposes it via MCP (Claude, Copilot) or HTTP API (Codex)
4. Your agent receives the full context and makes the code changes
5. Hot reload updates your browser automatically

Quick Start

Installation

npx @eyeglass/cli init

This interactive command will:

• Prompt you to select your AI agent(s): Claude Code, GitHub Copilot CLI, or OpenAI Codex CLI
• Install @eyeglass/inspector as a dev dependency
• Create agent-specific config files
• Configure your bundler (Vite, Next.js, CRA, or Remix)

Usage

# 1. Start your dev server
npm run dev

# 2. Start your AI agent
claude                    # Claude Code
gh copilot               # GitHub Copilot CLI
codex                    # OpenAI Codex CLI

# 3. Tell your agent to watch for requests
> listen for eyeglass    # or "eg" / "watch eyeglass"

Then in your browser:

• Click any element to select it (multi-select up to 5)
• Type your request in the Eyeglass panel
• Submit—Claude automatically receives it and starts working

💡 Tip: You never need to leave your browser. Claude watches for requests via long-polling.

Keyboard Shortcuts

Packages

Package	Description	Size	npm
@eyeglass/cli	CLI for project initialization	—
@eyeglass/inspector	Browser-side Web Component	~57kb
@eyeglass/bridge	MCP server connecting browser to Claude	—
@eyeglass/types	Shared TypeScript definitions	—

Supported Frameworks

Eyeglass works with any framework. For React, Vue, and Svelte, it extracts component names and file paths from framework internals. For vanilla JS or unsupported frameworks, it provides element identifiers (id, classes, data attributes) that Claude can use to locate the element.

Agent Integration

MCP Tools (Claude Code, Copilot CLI)

The bridge exposes these tools via Model Context Protocol:

HTTP API (OpenAI Codex CLI)

For agents that don't support MCP, the bridge also exposes a REST API:

Git Integration

Eyeglass automatically tracks changes using Git, making it easy to review and undo AI-generated modifications.

How It Works

1. Auto-commit on success — When Claude marks a request as complete (update_status("success")), Eyeglass automatically:

   • Stages all changes (git add -A)
   • Creates a commit with a tagged message: [eyeglass:<interaction-id>] <message>

2. One-click undo — In the Eyeglass hub (bottom-left of your browser), completed requests show an undo button (↩). Clicking it:

   • Finds the commit by its interaction ID
   • Runs git revert --no-edit <commit> to cleanly undo the changes
   • Creates a new revert commit (preserving history)

3. Settings — Click the gear icon (⚙) in the hub to access settings:

   • Auto-commit toggle — Enable/disable automatic commits (persisted in localStorage)

Example Git History

* a1b2c3d (HEAD) Revert "[eyeglass:abc123] Made button blue"
* f4e5d6c [eyeglass:abc123] Made button blue
* 9g8h7i6 [eyeglass:xyz789] Fixed header padding
* previous commits...

Requirements

• Your project must be a Git repository
• There must be uncommitted changes when Claude completes a task
• Git must be available in your PATH

Notes

• Auto-commit is enabled by default but can be toggled off in settings
• If you're not in a Git repo, Eyeglass silently skips committing (no errors)
• Empty changes (no files modified) are not committed
• Undo only works for changes that were committed by Eyeglass
• Each interaction gets a unique ID, so you can undo specific changes without affecting others

Configuration

Agent Config Files

Eyeglass creates agent-specific config files based on your selection:

{
  "mcpServers": {
    "eyeglass": {
      "command": "npx",
      "args": ["eyeglass-bridge"]
    }
  }
}

{
  "mcpServers": {
    "eyeglass": {
      "command": "npx",
      "args": ["eyeglass-bridge"]
    }
  }
}

Vite

// src/main.tsx (or main.ts)
import '@eyeglass/inspector';

Next.js

// app/layout.tsx
import '@eyeglass/inspector';

Manual Setup

Semantic Snapshot

When you select an element, Eyeglass captures comprehensive context:

interface SemanticSnapshot {
  // Element identification
  role: string;           // ARIA role (button, link, textbox, etc.)
  name: string;           // Accessible name
  tagName: string;        // HTML tag
  id?: string;            // Element ID
  className?: string;     // CSS classes
  dataAttributes?: Record<string, string>;

  // Framework context
  framework: {
    name: 'react' | 'vue' | 'svelte' | 'vanilla';
    componentName?: string;   // e.g., "SubmitButton"
    filePath?: string;        // e.g., "src/components/SubmitButton.tsx"
    lineNumber?: number;
    props?: Record<string, unknown>;
    ancestry?: string[];      // Parent component chain
  };

  // Accessibility
  a11y: {
    label: string | null;
    description: string | null;
    disabled: boolean;
    expanded?: boolean;
    checked?: boolean | 'mixed';
    hidden: boolean;
  };

  // Layout
  geometry: {
    x: number;
    y: number;
    width: number;
    height: number;
    visible: boolean;
  };

  // Styles
  styles: {
    display: string;
    position: string;
    flexDirection?: string;
    gridTemplate?: string;
    padding: string;
    margin: string;
    color: string;
    backgroundColor: string;
    fontFamily: string;
    zIndex: string;
  };

  // DOM Neighborhood (layout context)
  neighborhood?: {
    parents: Array<{
      tagName: string;
      className?: string;
      styles: {
        display: string;
        position: string;
        flexDirection?: string;
        alignItems?: string;
        justifyContent?: string;
        gap?: string;
        gridTemplate?: string;
      };
    }>;
    children: Array<{
      tagName: string;
      className?: string;
      count?: number;
    }>;
  };

  // Metadata
  timestamp: number;
  url: string;
}

Development

Setup

git clone https://github.com/donutboyband/eyeglass.git
cd eyeglass
npm install
npm run build

Testing

npx vitest            # Watch mode
npx vitest run        # Single run
npx vitest --coverage # With coverage

Project Structure

eyeglass/
├── packages/
│   ├── bridge/       # MCP server
│   │   └── src/
│   │       ├── index.ts    # Entry point
│   │       ├── mcp.ts      # MCP tool handlers
│   │       ├── http.ts     # Express server (SSE, REST)
│   │       └── store.ts    # State management
│   ├── cli/          # CLI tool
│   │   └── src/
│   │       └── index.ts    # Commands and project detection
│   ├── inspector/    # Browser component
│   │   └── src/
│   │       ├── index.ts        # Entry + auto-init
│   │       ├── inspector.ts    # Web Component UI
│   │       ├── snapshot.ts     # DOM snapshot capture
│   │       └── fiber-walker.ts # React/Vue/Svelte detection
│   └── types/        # Shared types
│       └── src/
│           └── index.ts    # TypeScript interfaces
├── vitest.config.ts  # Test configuration
└── package.json      # Workspace root

Troubleshooting

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/*)
3. Make your changes with tests
4. Commit your changes (git commit -m 'Hello feature')
5. Push to the branch (git push origin feature/*)
6. Open a Pull Request

License

MIT © donutboyband