MergeUI

Find and merge duplicate UI components in seconds.

• Scan — Finds all duplicate component clusters in your codebase automatically
• Inspect — Deep-compares two components with AI to identify shared features and differences
• Merge — Generates a merged component and rewrites all imports across your codebase

Quick Start

# Scan for duplicates (free, no API key needed)
npx mergeui scan ./src --no-llm

# Deep-compare two components
ANTHROPIC_API_KEY=sk-... npx mergeui inspect Select SearchSelect

# Merge with interactive feature selection
ANTHROPIC_API_KEY=sk-... npx mergeui merge Select SearchSelect --interactive

Why MergeUI?

Every large codebase has this problem: someone creates a new Select instead of reusing the existing one. Someone imports directly from MUI instead of using the design system wrapper. Over time, you end up with 5 different Selects, 3 different Cards, and nobody knows which one to use.

MergeUI fixes this by:

1. Scanning your entire codebase with AST analysis to find structurally similar components
2. Ranking matches using AI to understand semantic similarity (not just code similarity)
3. Merging selected features from duplicates into a single canonical component
4. Rewriting all imports across your codebase automatically

How It Works

npx mergeui scan ./src

Scanned 230 components

 #  Cluster                    Components  Usages  Est. savings
 1  Select/Dropdown variants   5           47      ~280 LOC
 2  Card layouts               3           23      ~150 LOC
 3  Modal wrappers             3           18      ~120 LOC
 4  Input fields               4           31      ~200 LOC
 5  Button variants            2           52      ~60 LOC

Total: ~810 LOC potential reduction

Installation

# Run directly (recommended)
npx mergeui scan ./src

# Or install globally
npm install -g mergeui

Commands

mergeui scan [dir]

Scan for duplicate component clusters.

| Flag | Default | Description | |------|---------|-------------| | --threshold | 0.6 | Similarity threshold (0-1) | | --max-files | 5000 | Maximum files to scan | | --no-llm | false | AST-only mode (free, no API key) | | --json | false | JSON output for piping | | --timeout | 120 | Timeout in seconds |

mergeui inspect <A> <B>

Deep-compare two components using AI. Shows shared features, differences, and merge advice.

mergeui merge <base> <donor>

Merge donor into base component. AI generates merged code and rewrites imports.

| Flag | Description | |------|-------------| | -i, --interactive | Guided feature selection | | --keep <features> | Features to keep from donor | | --exclude <features> | Features to exclude | | --dry-run | Preview without writing | | --no-rewrite | Skip import rewriting |

Configuration

MergeUI uses your Anthropic API key for inspect and merge commands. scan --no-llm works without any key.

Setup

# Option 1: Environment variable (recommended)
export ANTHROPIC_API_KEY=sk-ant-...

# Option 2: First-run prompt
npx mergeui inspect Select SearchSelect
# -> "Enter your Anthropic API key: "
# Saved to ~/.mergeui/config.json

Bring Your Own Key (BYOK)

MergeUI never stores, transmits, or logs your API key beyond local config. Your key goes directly to the Anthropic API.

| Variable | Required | Description | |----------|----------|-------------| | ANTHROPIC_API_KEY | For inspect/merge | Get one at console.anthropic.com |

Architecture

scan  -> Scanner (Babel AST) -> Matcher (fingerprinting) -> Clusterer (union-find) -> Terminal output
merge -> LLM (Claude) -> Merger -> Rewriter (ts-morph) -> Updated codebase

| Module | What it does | |--------|-------------| | Scanner | Parses JSX/TSX, extracts component signatures (props, hooks, structure) | | Matcher | Compares components using Jaccard similarity + tree edit distance | | Clusterer | Groups similar components using union-find with tag-bag pre-filtering | | LLM | Claude judges semantic similarity, extracts features, generates merged code | | Rewriter | Updates imports across codebase using ts-morph AST transforms |

Supported Patterns

• Function components (export function Button)
• Arrow components (export const Card = () => ...)
• Default exports (export default function Select)
• HOC wrappers (memo, forwardRef, React.memo)
• TypeScript interfaces and generics
• All CSS approaches (CSS Modules, styled-components, Tailwind, makeStyles)
• Vue/Svelte/Angular — planned for v2
• styled.div template components — planned

Requirements

• Node.js 18+
• ANTHROPIC_API_KEY for inspect and merge commands

Roadmap

• [x] AST-based duplicate scanning
• [x] AI-powered semantic comparison
• [x] Interactive merge with feature selection
• [x] Auto-import rewriting with ts-morph
• [ ] Full-scan LLM refinement (remove false positives)
• [ ] CI mode (mergeui ci for PR checks)
• [ ] VS Code extension
• [ ] Web UI with live component previews
• [ ] Multi-framework support (Vue, Svelte)
• [ ] Embeddings for semantic search

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — use it however you want.