imugi

Give AI eyes to see your frontend.

Figma design → pixel-perfect code, with zero manual CSS tweaking.

imugi is an MCP tool that captures your running UI, compares it against the original design using image similarity, and keeps pushing AI to fix the code until it's a perfect match.

Get Started · Docs · MCP Tools · Examples · Contributing

The Problem

You give AI a Figma design and ask it to build the frontend. The result looks... close. But then you spend the next 2 hours manually tweaking padding, font sizes, colors, and alignment — because AI has no way to verify what it actually produced.

imugi fixes this. It gives AI the ability to screenshot its own output, compare it pixel-by-pixel against the design, see exactly where the differences are, and fix them — automatically, in a loop, until the implementation matches the design.

No more eyeballing. No more manual CSS tweaking. The AI does it all.

How it works

Design Image → Code Generation → Screenshot → Compare → Analyze → Patch
                                                                     ↓
                                                              Score ≥ 95%? → Done!
                                                                     ↓ No
                                                                   Repeat

imugi uses SSIM (Structural Similarity) + pixelmatch + Claude Vision to compare design images against live rendered output, then automatically patches the code to close the gap. This is the Boulder Loop — it keeps rolling until your code matches the design.

Why imugi?

Quick Start

Step 1: Install & Setup

npm install -g imugi-ai

# One-click setup: installs Playwright browser, detects project, creates config
imugi init

Step 2: Add to your AI tool

Add imugi as an MCP server in your Claude Code or Cursor config (no API key required):

{
  "mcpServers": {
    "imugi": {
      "command": "npx",
      "args": ["-y", "imugi-ai", "mcp"]
    }
  }
}

Step 3: Build something

Ask your AI to implement a design — imugi handles the visual verification loop.

Implement this login page design. Here's the reference: ./login-design.png

That's it. imugi captures, compares, and patches until the output matches your design.

Examples

Design → Code (zero manual CSS)

A terminal-inspired hero section — designed in Figma/Pencil, implemented entirely by AI + imugi. No manual CSS tweaking involved.

Left: original design. Right: AI-generated code verified by imugi. The AI iterated autonomously until it achieved a pixel-perfect match — nav bar, hero CTA, flow diagram, MCP tools grid, footer, all matching the design down to the pixel.

See the full example at examples/hero-section/.

More Examples

Features

• Visual Comparison Engine — SSIM + pixel diff scoring with red heatmap showing exact diff locations

• Region Crop Pairs — Side-by-side crop images of each diff region (design vs your code) so AI can visually compare specific areas

• DOM Style Extraction — Extracts computed CSS from your running page (font-size, color, padding, etc.) and maps them to diff regions — AI knows exactly what CSS values to change

• Figma Spec Diff — When FIGMA_TOKEN is set, fetches exact design specs from Figma API and diffs them against your DOM: fontSize: design=42px → your code=48px. No guessing from pixels

• Boulder Loop — Automated iterative improvement: capture → compare → patch → repeat until 95%+ match

• MCP Server — Drop-in for Claude Code / Cursor / any MCP-compatible AI tool. No API key needed

• Figma Integration — Export Figma frames directly via URL (imugi figma <URL>), no manual export

• Project Auto-Detection — Detects React/Vue/Svelte/Next.js, Tailwind/CSS Modules/styled-components, TypeScript/JavaScript

• Smart Patching — Full rewrite for low scores (< 0.7), surgical CSS fixes for high scores (>= 0.7)

• Interactive Agent — Terminal UI with real-time iteration progress (powered by Ink)

• CI/CD Ready — GitHub Action for visual regression testing in your pipeline

Usage Modes

As MCP Server (Recommended)

imugi mcp

Works with Claude Code, Cursor, and any MCP-compatible tool. The AI calls imugi tools to verify and fix its own frontend output.

No API key needed for MCP mode. imugi provides the eyes (capture, compare, heatmap). Your AI editor provides the brain (code generation, patching). You provide nothing extra — zero additional cost.

As Interactive Agent

export ANTHROPIC_API_KEY=sk-ant-...
imugi

Then describe what you want:

> implement this design ./login-design.png

One-shot Generation

imugi generate ./design.png --output src/app/page.tsx

Compare Only

# Compare against a local screenshot file
imugi compare ./design.png --screenshot ./current.png

# Compare against a running dev server URL
imugi compare ./design.png --screenshot http://localhost:3000

Figma Export

# Export a Figma frame as PNG
imugi figma "https://www.figma.com/design/FILE_KEY/name?node-id=42-1234"

# Export at 3x scale with custom output path
imugi figma "https://www.figma.com/design/FILE_KEY/name?node-id=42-1234" -s 3 -o design.png

# Export and immediately compare against dev server
imugi figma "https://www.figma.com/design/FILE_KEY/name?node-id=42-1234" --compare

Requires a Figma personal access token via FIGMA_TOKEN environment variable or figma.token in config.

MCP Tools

Comparison Algorithm

The composite score combines multiple signals:

Beyond the score, imugi_iterate returns three layers of actionable feedback:

Strategy selection based on score:

Configuration

Create imugi.config.json in your project root:

{
  "comparison": {
    "threshold": 0.95,
    "maxIterations": 10
  },
  "rendering": {
    "port": 3000,
    "viewport": { "width": 1440, "height": 900 }
  }
}

Environment Variables

Architecture

src/
├── cli.ts              # CLI entry point (Commander.js)
├── mcp/server.ts       # MCP server (stdio transport)
├── agent/
│   ├── auth.ts         # OAuth PKCE + API key auth
│   ├── loop.ts         # Boulder Loop — iterative improvement
│   ├── session.ts      # State management
│   └── ui.tsx          # Terminal UI (Ink/React)
├── core/
│   ├── comparator.ts   # SSIM + pixelmatch + heatmap
│   ├── analyzer.ts     # Diff classification + strategy
│   ├── renderer.ts     # Playwright screenshot engine
│   ├── patcher.ts      # Code generation + patching
│   ├── context.ts      # Project tech stack detection
│   └── figma.ts        # Figma URL parsing + API export + design spec extraction
├── llm/
│   ├── client.ts       # Anthropic SDK wrapper
│   └── prompts.ts      # Prompt engineering
├── config/
│   ├── schema.ts       # Zod validation
│   ├── loader.ts       # Config loading (file + env + CLI)
│   └── defaults.ts     # Default configuration
└── types.ts            # Shared type definitions

Alternatives & Comparison

How does imugi compare to other design-to-code tools?

imugi is the only tool that measures design-to-code fidelity with an objective score and automatically iterates until the code matches the design. Other tools generate code in a single pass with no verification step.

Star History

If imugi helped you skip the manual CSS grind, consider giving it a star.

Development

git clone https://github.com/M00N7682/imugi.git
cd imugi
npm install
npm run build
npm test

See CONTRIBUTING.md for guidelines.

License

MIT