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.

Two failure modes dominate that loop:

• Invisible errors. A React hydration mismatch or a 404 hero image 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.

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.

Every frame above is real output. The screenshots are the tool's own JPEG payload and the console/DOM lines are its own text payload — regenerate them with node scripts/assets/capture-demo.mjs.

How it works

Install

Claude Code — install the plugin and you get the MCP server plus five skills and two subagents:

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
node scripts/smoke.mjs             # 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 hook):

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/pricing",
    "pageTitle": "Pricing",
    "viewport": "mobile (390x844)",
    "fullPage": false,
    "waitedMs": 1000,
    "captureMs": 1172,
    "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/hero.png", "method": "GET", "failure": "HTTP 404", "status": 404 }
  ],
  "simplifiedDOM": "<body class=\"...\">...</body>"
}

Prompts that work well

Check localhost:3000 on mobile and tell me what breaks.
Look at localhost:5173/pricing — the cards aren't aligned. Fix it.
Screenshot localhost:3000 with fullPage, then fix any spacing inconsistencies.
Are there any console errors on localhost:3000/checkout?
Compare localhost:3000 on desktop vs mobile and make the nav responsive.

The Claude Code plugin

Installing via the plugin adds a workflow layer on top of the raw tool, so you do not have to describe the process every time. Every skill is also model-invoked — saying "the pricing page looks broken on mobile" is enough to trigger one.

Plus a PostToolUse hook that flags any edit to .tsx/.jsx/.vue/.svelte/.css/.scss as unverified until the page is captured again.

The plugin ships from the plugin/ subdirectory rather than the repo root on purpose. Claude Code runs npm install inside any plugin directory containing a package.json, which pushed 113 MB of devDependencies into the plugin cache before this was fixed. It is now 20 KB.

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 node scripts/assets/measure-dom.mjs.

• 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

Full 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.

Resource management

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/
node scripts/smoke.mjs               # spawn dist/ and exercise it over real stdio
node scripts/validate-manifests.mjs  # plugin/marketplace/npm manifest consistency
npm run validate:plugin              # claude plugin validate .
node scripts/assets/measure-dom.mjs  # reproduce the DOM-reduction figure

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/         check-ui · responsive-audit · a11y-audit · console-triage · before-after
├── agents/         ui-debugger · ui-reviewer
└── hooks/          post-edit "this is unverified" reminder

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

scripts/
├── smoke.mjs               spawns dist/ and drives it over real stdio
├── validate-manifests.mjs  keeps npm + plugin + marketplace in sync
└── assets/                 regenerates the README GIF 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.

Roadmap

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

• Interaction before capture (click, hover, fill, scroll)

• 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.

MIT licensed — see LICENSE.

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