{"id":50949168,"url":"https://github.com/codebruinc/visual-matcher-ai","last_synced_at":"2026-06-17T23:32:33.486Z","repository":{"id":315573972,"uuid":"1060048032","full_name":"codebruinc/visual-matcher-ai","owner":"codebruinc","description":"A powerful visual comparison tool for AI coding agents to achieve pixel-perfect website matching","archived":false,"fork":false,"pushed_at":"2025-09-19T10:08:29.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-19T12:28:31.189Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://codebru.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codebruinc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T10:02:42.000Z","updated_at":"2025-09-19T10:08:32.000Z","dependencies_parsed_at":"2025-09-19T12:28:33.803Z","dependency_job_id":"45179103-6edd-41e6-825e-15e9aa4fd5e1","html_url":"https://github.com/codebruinc/visual-matcher-ai","commit_stats":null,"previous_names":["codebruinc/visual-matcher-ai"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codebruinc/visual-matcher-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebruinc%2Fvisual-matcher-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebruinc%2Fvisual-matcher-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebruinc%2Fvisual-matcher-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebruinc%2Fvisual-matcher-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codebruinc","download_url":"https://codeload.github.com/codebruinc/visual-matcher-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codebruinc%2Fvisual-matcher-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34470323,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-17T23:32:32.610Z","updated_at":"2026-06-17T23:32:33.478Z","avatar_url":"https://github.com/codebruinc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Visual Matcher AI 🎯\n\nA powerful visual comparison tool designed specifically for AI coding agents to achieve pixel-perfect website matching. Born from real-world experience building 1:1 website clones with AI assistance.\n\n## ✨ Features\n\n- **Pixel-Perfect Comparison**: Advanced image comparison using Puppeteer, Sharp, and Pixelmatch\n- **Smart Scroll Detection**: Automatically finds optimal scroll positions for best matching\n- **Continuous Monitoring**: Real-time visual regression testing during development\n- **AI Agent Integration**: Purpose-built for Claude Code, Cursor AI, and other AI coding tools\n- **CLI \u0026 API**: Both command-line interface and programmatic access\n- **Detailed Reporting**: Comprehensive similarity scores and visual diff generation\n\n## 📦 Installation\n\n### Global Installation (CLI)\n```bash\nnpm install -g visual-matcher-ai\n```\n\n### Local Installation (API)\n```bash\nnpm install visual-matcher-ai\n```\n\n## 🖥️ CLI Usage\n\n### Basic Comparison\n```bash\nvisual-matcher compare -u http://localhost:3000 -r ./reference.png\n```\n\n### Find Optimal Scroll Position\n```bash\nvisual-matcher find-best -u http://localhost:3000 -r ./reference.png --start 0 --end 1500 --step 50\n```\n\n### Continuous Monitoring\n```bash\nvisual-matcher watch -u http://localhost:3000 -r ./reference.png --interval 15\n```\n\n### Advanced Options\n```bash\nvisual-matcher compare \\\n  --url http://localhost:3000 \\\n  --reference ./target-design.png \\\n  --output ./results \\\n  --width 1920 \\\n  --height 880 \\\n  --scroll-y 900 \\\n  --threshold 0.1\n```\n\n## 🔧 API Usage\n\n### Quick Comparison\n```javascript\nconst { compareScreenshots } = require('visual-matcher-ai');\n\nconst result = await compareScreenshots('http://localhost:3000', './reference.png', {\n  viewport: { width: 1920, height: 880 },\n  scrollY: 900\n});\n\nconsole.log(`Similarity: ${result.similarity}%`);\n```\n\n### Advanced Usage\n```javascript\nconst { VisualMatcher } = require('visual-matcher-ai');\n\nconst matcher = new VisualMatcher({\n  viewport: { width: 1920, height: 880 },\n  threshold: 0.1\n});\n\n// Find best scroll position\nconst bestMatch = await matcher.findOptimalScrollPosition(\n  'http://localhost:3000',\n  './reference.png',\n  { startY: 0, endY: 2000, step: 50 }\n);\n\n// Continuous monitoring\nawait matcher.continuousMatch('http://localhost:3000', './reference.png', {\n  interval: 15000,\n  onUpdate: (result) =\u003e {\n    console.log(`Current similarity: ${result.similarity}%`);\n    if (result.similarity \u003e 95) {\n      console.log('🎯 Target achieved!');\n    }\n  }\n});\n\nawait matcher.close();\n```\n\n## 🤖 AI Agent Integration\n\n### Claude Code\n```markdown\nI'm building a website clone and need to achieve 95%+ visual similarity.\n\n1. Start visual monitoring:\n   ```bash\n   visual-matcher watch -u http://localhost:3000 -r ./target.png --interval 10\n   ```\n\n2. Make incremental changes to match the reference\n3. Monitor similarity scores in real-time\n4. Focus on major differences (\u003e5% improvement) before micro-optimizations\n```\n\n### Cursor AI Integration\n```javascript\n// Add to your workspace settings\n{\n  \"visualMatcher.autoStart\": true,\n  \"visualMatcher.reference\": \"./design-reference.png\",\n  \"visualMatcher.target\": \"http://localhost:3000\",\n  \"visualMatcher.threshold\": 95\n}\n```\n\n### GitHub Codespaces / Dev Containers\n```dockerfile\n# Add to your Dockerfile\nRUN npm install -g visual-matcher-ai\n\n# In your dev container\nEXPOSE 3000\nCMD [\"visual-matcher\", \"watch\", \"-u\", \"http://localhost:3000\", \"-r\", \"/workspace/reference.png\"]\n```\n\n## 📋 Workflow Examples\n\n### Perfect Landing Page Clone\n```bash\n# 1. Find optimal viewport and scroll position\nvisual-matcher find-best -u https://target-site.com -r ./downloaded-reference.png\n\n# 2. Start continuous monitoring during development\nvisual-matcher watch -u http://localhost:3000 -r ./reference.png --scroll-y 900\n\n# 3. Build and iterate until 95%+ similarity achieved\n```\n\n### Component-Level Matching\n```javascript\nconst matcher = new VisualMatcher({\n  viewport: { width: 1200, height: 800 }\n});\n\n// Test specific component sections\nconst headerMatch = await matcher.compareImages('./header-reference.png', './current-header.png');\nconst heroMatch = await matcher.compareImages('./hero-reference.png', './current-hero.png');\n\nconsole.log(`Header: ${headerMatch.similarity}%, Hero: ${heroMatch.similarity}%`);\n```\n\n## ⚙️ Configuration Options\n\n### VisualMatcher Options\n```javascript\n{\n  headless: true,                    // Run browser in headless mode\n  viewport: { width: 1920, height: 1080 },  // Browser viewport size\n  threshold: 0.1,                    // Pixelmatch sensitivity (0-1)\n  includeAA: false                   // Include anti-aliasing in comparison\n}\n```\n\n### Comparison Options\n```javascript\n{\n  scrollY: 900,                      // Specific scroll position\n  fullPage: false,                   // Full page screenshot\n  outputPath: './screenshot.png',    // Custom screenshot path\n  diffPath: './diff.png'            // Custom diff image path\n}\n```\n\n## 📊 Understanding Results\n\n### Similarity Scores\n- **95-100%**: Pixel-perfect match ✨\n- **85-94%**: Excellent match ✅\n- **70-84%**: Good match, minor tweaks needed ⚠️\n- **\u003c70%**: Major structural differences ❌\n\n### Optimization Strategy\n1. **Start with major layout issues** (backgrounds, positioning)\n2. **Fix structural problems** before micro-optimizations\n3. **Use proper viewport and scroll position** from reference\n4. **Focus on 5-10% improvements** rather than 1-2% tweaks\n5. **Test at optimal scroll position** for accurate comparison\n\n## 🛠️ Common Issues \u0026 Solutions\n\n### Browser Compatibility\n```bash\n# Install Chromium dependencies on Linux\napt-get install -y chromium-browser\n\n# Docker Alpine\napk add chromium\n```\n\n### Memory Issues\n```javascript\n// Limit concurrent operations\nconst matcher = new VisualMatcher({ headless: true });\n// Always close matcher when done\nawait matcher.close();\n```\n\n### Network Timeouts\n```javascript\n// Increase timeout for slow sites\nawait page.goto(url, {\n  waitUntil: 'networkidle0',\n  timeout: 60000\n});\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! This tool was created from real experience building pixel-perfect clones with AI coding agents.\n\n### Development Setup\n```bash\ngit clone https://github.com/codebruinc/visual-matcher-ai.git\ncd visual-matcher-ai\nnpm install\nnpm run test\n```\n\n### Running Examples\n```bash\nnpm run example  # Run CodeBru example\n```\n\n## 📄 License\n\nMIT © 2025 CodeBru, Inc.\n\n## 🎉 Success Stories\n\nThis tool was battle-tested while building a 1:1 clone of CodeBru.com, achieving 86% similarity through systematic optimization. Key learnings:\n\n- **Proper viewport matching** is crucial (880px vs 1080px made huge difference)\n- **Optimal scroll position** discovery improved accuracy by 40%\n- **Continuous monitoring** prevented regressions during development\n- **Focus on major fixes first** - 5% improvements vs 1% micro-optimizations\n\n---\n\nBuilt with ❤️ for the AI coding community by [CodeBru.com](https://codebru.com). Happy cloning! 🚀","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodebruinc%2Fvisual-matcher-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodebruinc%2Fvisual-matcher-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodebruinc%2Fvisual-matcher-ai/lists"}