VibeLens

The problem

AI assistants write frontend code well but cannot see what the browser actually rendered. So you become the framebuffer: you open the page, spot the bug, and describe it in prose — "the button is overflowing the card", "spacing looks off on mobile" — and the model guesses which selector you mean.

Three failure modes dominate that loop:

• Invisible errors. A hydration mismatch or a 404 asset lives in the console, not in your description.

• Selector hallucination. The model edits .btn-primary when the element actually carries .cta-button, because it is recalling its own earlier output instead of reading the DOM.

• Generated-looking UI. Untouched framework accent, one radius on everything, no type scale, no empty or focus states. It works, and it looks like nobody made it.

Related MCP server: pagelens

The fix

VibeLens is an MCP server that closes the loop. One tool call returns a screenshot, the console and network diagnostics, and a token-optimized DOM snapshot — so the model reasons from evidence instead of memory. The Claude Code plugin adds twelve skills on top, including a design-craft set aimed squarely at the third problem.

Every frame is real output. The screenshots are the tool's own JPEG payload and the console and DOM lines are its own text payload — regenerate them with npm run assets:gif.

How it works

Install

Claude Code — install the plugin and you get the MCP server plus twelve skills, four subagents and two advisory hooks:

claude plugin marketplace add soumyachk101/VibeLens
claude plugin install vibelens@vibelens

Every other IDE — VibeLens is a plain MCP server on npm. There is no global install step; npx fetches it on first run:

npx playwright install chromium   # one-time, ~95 MB

Then paste the config block for your IDE from the next section.

Requirements: Node.js 20 or newer (Playwright 1.62 requires it) and Chromium for Playwright.

git clone https://github.com/soumyachk101/VibeLens.git
cd VibeLens
npm install
npx playwright install chromium
npm run build                      # emits dist/
npm test                           # 63 tests, includes real browser captures
npm run smoke                      # end-to-end check over real stdio

Then point your IDE at node /absolute/path/to/VibeLens/dist/index.js.

Configure your IDE

VibeLens speaks MCP over stdio, so every MCP-capable client takes the same shape:

{
  "mcpServers": {
    "vibelens": {
      "command": "npx",
      "args": ["-y", "mcp-vibelens@1"]
    }
  }
}

As a plugin (recommended — bundles the skills, agents and hooks):

claude plugin marketplace add soumyachk101/VibeLens
claude plugin install vibelens@vibelens

Or as a bare MCP server:

claude mcp add vibelens --scope user -- npx -y mcp-vibelens@1      # every project
claude mcp add vibelens --scope project -- npx -y mcp-vibelens@1   # writes .mcp.json for the team

Verify with /mcp in a session — vibelens should be listed as connected.

codex mcp add vibelens -- npx -y mcp-vibelens@1

Or edit ~/.codex/config.toml directly. Codex shares this config between the CLI and the IDE extension, so it only needs doing once:

[mcp_servers.vibelens]
command = "npx"
args = ["-y", "mcp-vibelens@1"]

Check with codex mcp list. Codex only supports local stdio servers, which is exactly what VibeLens is.

Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects, with the JSON block above. Then enable vibelens under Settings → MCP.

Open the MCP config from the UI — three-dot menu in chat → MCP Servers → Manage MCP Servers → View raw config, or Settings → Customizations → Open MCP Config — and paste the same block. Depending on your build the file lives at:

• ~/.gemini/antigravity/mcp_config.json

• ~/.gemini/config/mcp_config.json (newer builds and the Antigravity CLI)

Using the in-app menu is the safest way to open the right one.

~/.codeium/windsurf/mcp_config.json, same JSON block.

.vscode/mcp.json:

{
  "servers": {
    "vibelens": { "command": "npx", "args": ["-y", "mcp-vibelens@1"] }
  }
}

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, same JSON block. Restart the app afterwards.

The tool

inspect_localhost_ui

Returns two content blocks: an image (base64 JPEG, quality 75) and a text block containing JSON:

{
  "summary": {
    "url": "http://localhost:3000/health",
    "pageTitle": "Service health",
    "viewport": "desktop (1920x1080)",
    "fullPage": false,
    "waitedMs": 1000,
    "captureMs": 1253,
    "consoleErrors": 1,
    "consoleWarnings": 0,
    "uncaughtPageErrors": 0,
    "failedRequests": 1,
    "domTruncated": false
  },
  "consoleLogs": [
    { "level": "error", "text": "Hydration failed...", "location": "http://localhost:3000/app.js:42:13" }
  ],
  "uncaughtPageErrors": ["TypeError: Cannot read properties of undefined"],
  "failedRequests": [
    { "url": "http://localhost:3000/avatar.png", "method": "GET", "failure": "HTTP 404", "status": 404 }
  ],
  "simplifiedDOM": "<body class=\"...\">...</body>"
}

It is read-only and local-only. It observes a page; it cannot click, hover, type, scroll, or reach a public host. That constraint shapes every skill below — hover and :focus-visible styles are read from the source, not observed.

Prompts that work well

Check localhost:3000 on mobile and tell me what breaks.
Look at localhost:5173/settings — the cards aren't aligned. Fix it.
Does localhost:3000/checkout throw anything in the console?
This page looks AI-generated. Tell me why, then fix the worst of it.
The accent is just default Tailwind blue — give me a real palette.
Compare localhost:3000 on desktop vs mobile and make the nav responsive.

What the plugin adds

The raw tool gives the model eyes. The plugin gives it a method — and a set of skills aimed at the thing screenshots alone do not fix: UI that works but looks like nobody designed it.

Debugging

Design craft — the anti-slop set

Verification

Subagents

Advisory hooks

Both are PostToolUse, both are advisory only — they print one line and always exit 0, so they can never block a tool call or edit a file.

Every skill is model-invoked as well as slash-invoked. Saying "this looks AI-generated" reaches design-review; "the modal just snaps open" reaches motion-system; "prove that fix worked" reaches before-after.

The design knowledge base

The design skills stay short by citing a shared reference instead of restating it. It is written for an agent mid-task: tables, thresholds and code, no essays.

Start at docs/design/README.md for the index and the working order.

How it protects your context window

A raw document.body.outerHTML from a modern app is mostly noise. VibeLens sanitizes it inside the browser, before it ever reaches the model.

Reproduce that measurement yourself with npm run assets:measure.

• Removed: <script>, <style>, <noscript>, <template>, <link>, <meta>, <base>, <title> and HTML comments.

• Collapsed to an empty placeholder: <svg>, <canvas>, <iframe>, <video>, <audio>, <object>, <embed>, <map>, <picture> — the box still appears in the tree because it affects layout, but its internals are gone.

• Attributes kept: id, class, role, aria-*, data-testid/-test/-cy/-qa, plus form and table structure attributes.

• Attributes shortened: data: URIs become data:image/png[stripped]; anything over 300 chars is truncated; inline style over 120 chars is cut.

• Text nodes: whitespace collapsed, each node capped at 160 chars.

• Hard cap: 20,000 characters, with an explicit <!-- VibeLens: DOM truncated ... --> marker so the model knows the tree is partial.

Architecture

Module-by-module detail, the request lifecycle and the resource model live in docs/ARCHITECTURE.md. The reasoning behind each significant choice is recorded as an ADR in docs/adr/:

Security

VibeLens drives a real browser on your machine, so an unvalidated URL would be a server-side request forgery (SSRF) primitive. Every URL is checked before Chromium launches.

Allowed: localhost, *.localhost, 127.0.0.0/8, 0.0.0.0, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, [::1], IPv6 unique-local (fc00::/7) and link-local (fe80::/10).

Blocked:

• Every public hostname and IP address.

• Any DNS name that is not localhost-based — resolving one invites DNS rebinding, so hostnames are refused rather than looked up.

• Cloud instance-metadata endpoints (169.254.169.254, 169.254.170.2, fd00:ec2::254, 100.100.100.200) and all of IPv4 link-local 169.254.0.0/16.

• Non-HTTP schemes (file:, ftp:, javascript:, ...).

• URLs containing credentials (http://user:pass@...).

Two further points worth knowing:

• The tool is annotated readOnlyHint — it observes a page, it never modifies your project, and it cannot click, type or scroll.

• Page content is untrusted input. Text scraped from a rendered page could contain instructions aimed at your assistant. Treat the DOM snapshot as data, never as direction.

To report a vulnerability, see SECURITY.md.

Each call launches an ephemeral Chromium and closes it in a finally block, so a failed capture cannot leave a zombie browser behind. This matters on Apple Silicon laptops where every stray Chromium costs hundreds of MB of RSS.

Troubleshooting

The long-form version, including per-IDE diagnosis, is in docs/TROUBLESHOOTING.md. Common questions are answered in docs/FAQ.md.

Development

npm run dev                  # run the server from source over stdio
npm run typecheck            # tsc --noEmit
npm test                     # vitest: security, DOM, capture e2e, MCP protocol
npm run build                # emit dist/
npm run smoke                # spawn dist/ and exercise it over real stdio
npm run validate:manifests   # npm + plugin + marketplace + docs consistency
npm run validate:plugin      # claude plugin validate for both manifests
npm run assets:measure       # reproduce the DOM-reduction figure
npm run assets:gif           # regenerate the README animation from real captures
npm run site:build           # build the documentation site into site-dist/
npm run site:check           # link-check it, then inspect it with VibeLens itself

Repository map

src/
├── index.ts        executable entrypoint: wires the server to stdio
├── server.ts       MCP server + inspect_localhost_ui registration
├── browser.ts      Playwright capture engine
├── dom.ts          in-page DOM sanitizer + truncation
├── security.ts     SSRF guard (URL allowlist)
└── types.ts        shared types, viewport presets, payload limits

tests/              vitest suites, incl. real Chromium captures
├── security.test.ts        44 allow/block cases
├── dom.test.ts             truncation boundaries
├── capture.test.ts         end-to-end against a noisy fixture page
├── server.test.ts          real MCP client over InMemoryTransport
└── fixture-server.ts       the deliberately broken fixture page

plugin/             what Claude Code installs — no package.json, on purpose
├── .claude-plugin/plugin.json
├── .mcp.json       launches npx -y mcp-vibelens@1
├── skills/         12 skills: 4 debugging · 7 design craft · 1 verification
├── agents/         ui-debugger · ui-reviewer · design-reviewer · frontend-builder
└── hooks/          two advisory PostToolUse reminders

docs/
├── ARCHITECTURE.md         modules, lifecycle, resource and token model
├── design/                 the anti-slop, type, colour, layout and motion rules
├── adr/                    six architecture decision records
├── PRD-TRD.md              product + technical requirements
├── TROUBLESHOOTING.md      every error code, per-IDE diagnosis
└── FAQ.md                  honest answers, including the limitations

site/                   hand-authored design system for the docs site
├── styles.css      tokens, type scale, themes; no framework
└── app.js          theme toggle, copy buttons, TOC highlight

scripts/
├── smoke.mjs               spawns dist/ and drives it over real stdio
├── validate-manifests.mjs  keeps npm + plugin + marketplace + docs in sync
├── site/                   static site generator + its own link checker
└── assets/                 regenerates the README animation and measurements

.claude-plugin/marketplace.json   one-plugin marketplace catalog
.github/                          CI, tag-driven release, issue forms, CODEOWNERS

Contributing

Start with CONTRIBUTING.md — it lists the seven invariants that must not break (chief among them: never write to stdout, it is the MCP transport) and the verification checklist every PR must pass. Project guidance for AI agents working in this repo lives in CLAUDE.md.

Release process: RELEASE.md. Version history: CHANGELOG.md. Conduct: CODE_OF_CONDUCT.md.

Roadmap

• Element-scoped capture (selector: "#navbar")

• Interaction before capture (click, hover, fill, scroll) — would let the state-matrix skills observe hover and focus instead of reading them

• Multi-viewport diffing in a single call

• Full network waterfall for failed API calls

• Accessibility-tree output alongside the DOM

Ideas and votes belong in Discussions or a feature request.

Free forever, MIT licensed — see LICENSE. No paid tier, no hosted service, no telemetry.

If VibeLens saved you a round of "no, the other button", a star helps other people find it.