BrowserLens

BrowserLens is a local browser feedback loop for AI-assisted frontend development.

It turns a frontend bug into a reproducible local capsule:

repro -> browser evidence -> AI prompt -> fix verification -> regression test

Bug Capsule Workflow

npx -y @dev-built/browserlens@latest diagnose http://localhost:3000/products \
  --viewport 390x844 \
  --issue "Product card overflows after adding to cart" \
  --steps "click \"Add to cart\"" \
  --selector ".ProductCard" \
  --project-root /path/to/project

npx -y @dev-built/browserlens@latest prompt --last --project-root /path/to/project
npx -y @dev-built/browserlens@latest verify --last --project-root /path/to/project
npx -y @dev-built/browserlens@latest export-test --last --project-root /path/to/project
npx -y @dev-built/browserlens@latest open --last --project-root /path/to/project

BrowserLens stores local artifacts in the active project:

.browserlens/sessions/<session-id>/
  before.png
  after.png
  diff.png
  session.json
  prompt.md
  repro.browserlens.json
  validation.json
  suggested-test.spec.js

If your MCP host launches tools from another directory, pass projectRoot in the MCP tool call or use --project-root <path> with the CLI.

AI agents should read BROWSERLENS.md before their first tool call. It defines when to use BrowserLens, when to avoid it, tool costs, context escalation, profiles, confidence levels, and common mistakes.

When To Use BrowserLens

BrowserLens is the browser evidence and verification layer. It is not meant to replace code search for every issue.

Use code-first for:

• business logic bugs
• data mapping bugs
• API/backend bugs
• unit test failures
• compile errors

Use BrowserLens-first for:

• layout issues
• responsive bugs
• overflow, clipping, z-index, visibility, and focus issues
• user interaction failures
• browser-only regressions
• visual before/after verification

For logic bugs, the best workflow is usually:

read ticket -> search code -> fix -> unit test -> BrowserLens verify rendered UI

For visual bugs:

BrowserLens inspect -> fix -> BrowserLens verify -> export regression test

MCP

{
  "mcpServers": {
    "browserlens": {
      "command": "npx",
      "args": ["-y", "@dev-built/browserlens", "mcp"]
    }
  }
}

Primary MCP tools:

• browserlens_open_browser
• browserlens_status
• browserlens_health
• browserlens_restart
• browserlens_navigate
• browserlens_current_page
• browserlens_pick_element
• browserlens_capture_current_page
• browserlens_diagnose_issue
• browserlens_verify_fix
• browserlens_export_test
• browserlens_generate_prompt
• browserlens_get_last_session

MCP capture and validation tools return compact responses by default to reduce token use. Full evidence is saved locally in .browserlens/sessions/<session-id>/session.json. Pass detail: "standard" for source candidates and runtime summaries, or detail: "full" only when the agent truly needs the complete session object.

Context Levels

BrowserLens keeps browser context small by default.

• contextLevel: "minimal": default. Captures URL, viewport, selected element, accessibility snapshot, screenshot, and validation. Skips console/network unless explicitly asserted.
• contextLevel: "debug": adds console errors and failed network requests only.
• contextLevel: "deep": keeps broader console/network output with limits.

Workflow profiles:

• profile: "logic": minimizes browser context and skips screenshots by default.
• profile: "visual": browser-first debugging with screenshot and debug runtime context.
• profile: "regression": verification-focused capture with richer browser evidence.

Useful runtime controls:

• timeoutMs, navigationTimeoutMs, actionTimeoutMs
• includeConsole, includeNetwork, includeScreenshot, includeSnapshot
• consoleLevel, failedOnly, maxEntries, maxChars

Explicit include flags override profile defaults, so profile: "logic" with includeScreenshot: true still saves screenshot evidence. Console/network allowlists are applied to validation, inline responses, and generated prompts so allowed production noise does not distract the AI.

Repro steps support wait for navigation / wait for page load and wait until changed for browser flows where an interaction changes the page before capture.

Viewport validation is strict. If you request 390x844 and Chrome reports a different actual viewport, BrowserLens fails viewport-matches-request and skips responsive checks instead of reporting a misleading pass.

Browser Skill Mode

For MCP clients, BrowserLens can keep a browser session open so an agent can inspect and interact with the page before creating a bug capsule.

Typical agent flow:

1. browserlens_open_browser
2. browserlens_navigate
3. browserlens_pick_element
4. browserlens_capture_current_page
5. browserlens_verify_fix
6. browserlens_export_test

The picker injects a temporary overlay into Chrome. The user clicks the broken element, BrowserLens captures the selector and element context, then browserlens_capture_current_page saves the normal .browserlens/sessions/<session-id>/ artifacts.

Browser-session MCP tools:

• browserlens_open_browser
• browserlens_close_browser
• browserlens_navigate
• browserlens_current_page
• browserlens_take_screenshot
• browserlens_page_snapshot
• browserlens_browser_console
• browserlens_browser_network
• browserlens_click
• browserlens_fill
• browserlens_type
• browserlens_press
• browserlens_pick_element
• browserlens_capture_current_page
• browserlens_record_start
• browserlens_record_stop

Validation Contract

Use --assert, --ignore, --allow-console, and --allow-network when an app intentionally has behavior that BrowserLens would otherwise flag.

browserlens verify --last \
  --ignore no-network-failures \
  --allow-console "ResizeObserver loop" \
  --expect-text "Checkout" \
  --project-root /path/to/project

Available built-in assertions:

• viewport-matches-request
• no-horizontal-overflow
• selected-element-exists
• selected-element-visible
• selected-element-within-viewport
• selected-element-contains-text
• selected-element-value-equals
• url-matches
• no-console-errors
• no-network-failures
• visual-diff-under-threshold

Visual diff is generated during verify when a session has both before.png and after.png. It is informational unless visual-diff-under-threshold is explicitly asserted.

Useful assertion inputs:

• --expect-text <text> for selected-element-contains-text
• --expect-value <value> for selected-element-value-equals
• --url-pattern <text-or-/regex/> for url-matches
• --allow-console <text-or-/regex/> and --allow-network <text-or-/regex/> for intended dev noise

Figma / Design References

BrowserLens does not depend on Figma MCP. If an AI host already has Figma MCP, use Figma as the intended design reference and BrowserLens as the running-browser truth.

Pass compact design metadata when useful:

browserlens diagnose http://localhost:3000/products \
  --selector ".ProductCard" \
  --design-url "https://figma.com/file/..." \
  --design-node "12:34" \
  --design-viewport 390x844 \
  --design-notes "Mobile product card frame"

The generated prompt includes this design pointer but does not dump Figma JSON. The AI should call Figma MCP separately only for the specific frame or component details it needs.

Optional Source Annotations

For better React/Vite source candidates:

import react from "@vitejs/plugin-react";
import browserLensSourceAnnotation from "@dev-built/browserlens/source-annotation";

export default {
  plugins: [
    react({
      babel: {
        plugins: [browserLensSourceAnnotation]
      }
    })
  ]
};

For Next.js, add the plugin in .babelrc:

{
  "presets": ["next/babel"],
  "plugins": ["@dev-built/browserlens/source-annotation"]
}

This is optional; BrowserLens still works through DOM evidence and heuristic source search without it.

For AI-agent instructions, see BROWSERLENS.md and AI_USAGE.md.

Scope

• Plain JavaScript ESM.
• Chrome-first via Chrome DevTools MCP.
• Localhost-only capture by default.
• Isolated browser profile by default.
• Local JSON, Markdown, screenshots, and generated test artifacts.
• No PageAgent dependency.
• No required browser extension.
• No direct AI API calls.
• No automatic code patching.

Development

npm install
npm test
node ./bin/browserlens.js --help