Kaleidoscope

Kaleidoscope is a local-first responsive visual QA tool for web apps and coding agents. It lets you preview a page across real device emulation profiles, capture evidence, inspect rendered elements, and verify a UI edit against a structured layout baseline.

Use the visual workspace when you want to review a page yourself. Use the included MCP server when an agent needs browser evidence before or after changing UI code.

Why Kaleidoscope

Code can tell an agent what it changed; it cannot prove what the browser rendered. Kaleidoscope closes that gap with a tight browser-feedback loop:

1. capture a page across selected device profiles;
2. make a UI change;
3. recapture after the app rebuilds; and
4. return a concise noChange, changed, or inconclusive verdict, with the affected elements and source locations when available.

It is deliberately local-first: the server binds to loopback by default and inspect mode is restricted to trusted local pages.

What You Can Do

Review responsive layouts visually

• Load local or public HTTP/HTTPS pages once and compare mobile, tablet, and desktop profiles side by side.
• Pin device frames, switch quickly between profiles, and use a stacked comparison view on narrow screens.
• Use Playwright device emulation for supported profiles, including the appropriate mobile/touch defaults where available.

Capture visual evidence

• Capture viewport or full-page screenshots across several devices in one run.
• Save screenshots locally and return chat-ready image paths, Markdown image tags, resource links, and inline previews when the MCP client supports them.
• Compare two captured PNGs pixel by pixel and produce a highlighted diff image with exact mismatch metrics.

Verify a UI edit structurally

• Capture a structured layout baseline across one or more devices before editing.
• Recapture after the edit and compare visible elements for additions, removals, text changes, and significant geometry changes.
• Receive a short no-change verdict when the rendered layout is stable; otherwise receive a ranked, source-attributed summary of affected elements.

Layout comparison uses stable selectors and fallback identities where possible. Pixel comparison is available separately for screenshots captured at matching dimensions.

Discover failures between device presets

• Sweep a continuous viewport range rather than checking only a few named devices.
• Return compact sampled width ranges for deterministic failures: document-level horizontal overflow and visible interactive controls clipped horizontally.
• Start with a clear, concrete signal instead of asking an agent to inspect dozens of screenshots. A clear result means none of the currently supported checks found a problem, not that every possible visual defect has been ruled out.

Connect a rendered element to its code

• Find likely visible elements from a natural-language query such as “save button” or “hero section.”
• Inspect a selected element on a trusted local page and return viewport context plus runtime source metadata when it is available.
• Use the same source attribution in layout comparison results to help an agent move from a rendered regression to the responsible component.

Give coding agents browser tools

Kaleidoscope is available as a stdio MCP server for Claude Code, Codex, Cursor, Windsurf, VS Code, and other MCP clients. It can start its packaged runtime automatically, capture artifacts, inspect local pages, and return structured results instead of only prose.

Visual Tour

Capture multiple devices in one pass Queue mobile, tablet, and desktop screenshots from the sidebar without leaving the preview workflow.	Compare layouts side by side Pin devices and inspect how the same page behaves across very different breakpoints.
Keep reviewing on narrow screens Comparison mode falls back to a stacked layout so the workspace stays usable on smaller displays.	Start local, then automate Begin with localhost shortcuts such as 3000, then move into inspect, screenshots, or MCP-driven verification.

Agent Workflows

Prove an edit did not disturb the rest of the page

Ask your agent to:

Use Kaleidoscope to capture a layout baseline for http://localhost:3000/checkout on iphone-14, ipad, and desktop. After I edit the checkout form, wait for the app to reload and compare it with the baseline. Report only meaningful layout or text changes and their source locations.

The agent can use kaleidoscope_read_layout, wait for the target app to rebuild, then call kaleidoscope_after_edit. Layout captures are stored in the running server for a limited time; they are not durable project baselines yet.

Find the code behind a rendered problem

On http://localhost:3000/checkout, find the save button on an iPhone 16 viewport and inspect its source under c:/Code/my-app/src.

Use discover_page_elements to obtain ranked selector candidates, then inspect_element_source for the source payload. Inspect mode only accepts loopback URLs.

MCP Client Setup

No global install is required. Configure your MCP client to run the package through npx:

npx -y kaleidoscope-mcp-server@latest

Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, and similar clients:

{
  "mcpServers": {
    "kaleidoscope": {
      "command": "npx",
      "args": ["-y", "kaleidoscope-mcp-server@latest"],
      "env": {
        "KALEIDOSCOPE_SERVER_URL": "http://localhost:5000"
      }
    }
  }
}

Codex config.toml:

[mcp_servers.kaleidoscope]
command = "npx"
args = ["-y", "kaleidoscope-mcp-server@latest"]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

[mcp_servers.kaleidoscope.env]
KALEIDOSCOPE_SERVER_URL = "http://localhost:5000"

Codex desktop connector UI:

• Name: kaleidoscope
• Transport: STDIO
• Command to launch: npx
• Arguments: -y, kaleidoscope-mcp-server@latest
• Environment variable: KALEIDOSCOPE_SERVER_URL=http://localhost:5000
• Working directory: leave blank

The npm package includes the Kaleidoscope MCP server, backend, and built web client. When an MCP tool needs Kaleidoscope and no server is already running, it can start the packaged runtime automatically.

Optional Global Install

npm install -g kaleidoscope-mcp-server@latest

Then run kaleidoscope-mcp from the MCP client configuration instead of npx.

MCP Tool Reference

Tool	Use it for
kaleidoscope_status	Checking the local Kaleidoscope runtime.
kaleidoscope_list_devices	Listing supported device profiles and default screenshot devices.
preview_responsive	Opening a URL in the Kaleidoscope multi-device workspace.
capture_screenshots	Saving viewport or full-page screenshots across selected device profiles.
compare_screenshots	Comparing two captured PNGs and producing mismatch metrics plus a diff image.
discover_page_elements	Finding visible elements from a natural-language query.
inspect_element_source	Resolving a local rendered element to source context.
kaleidoscope_read_layout	Capturing a structured, optionally source-attributed layout baseline.
kaleidoscope_after_edit	Recapturing and comparing a page after a known rebuild.
kaleidoscope_scan_breakpoints	Sweeping a width range to find sampled horizontal-overflow and clipped-control failures.

The tool descriptions above are also exposed to MCP clients at runtime, so agents can discover the available structured inputs and outputs directly.

Device Profiles

The shared device catalog includes iPhone 14–17, Samsung Galaxy S21/S24/S24 Ultra/S25 Ultra, Pixel 6, iPad, iPad Pro, MacBook Air, Desktop HD, and Desktop 4K. Use kaleidoscope_list_devices for the authoritative runtime list and dimensions.

Environment Options

• KALEIDOSCOPE_SERVER_URL: Kaleidoscope backend URL. Defaults to http://localhost:5000.
• KALEIDOSCOPE_REQUEST_TIMEOUT_MS: MCP request timeout. Defaults to 60000.
• KALEIDOSCOPE_WORKSPACE_ROOT: source-inspection root for local projects.
• KALEIDOSCOPE_PROXY_TIMEOUT_MS: proxy request timeout. Defaults to 30000.
• KALEIDOSCOPE_PROXY_MAX_RESPONSE_BYTES: proxy response byte limit. Defaults to 10485760.
• KALEIDOSCOPE_LAYOUT_CAPTURE_MAX_AGE_MS: how long in-memory layout captures remain available. Defaults to 7200000 (two hours).
• KALEIDOSCOPE_LAYOUT_CAPTURE_MAX_COUNT: maximum in-memory layout captures retained by the server. Defaults to 50.

Current Boundaries

• Pixel comparison requires two PNGs with identical dimensions; persistent named baselines and broad automatic visual issue finding are not yet provided.
• Breakpoint scanning currently detects horizontal document overflow and horizontally clipped in-viewport interactive controls. It reports sampled ranges, not exact CSS-media-query boundaries, and it does not yet diagnose the responsible source rule.
• Layout and screenshot capture use the supported Chromium/Playwright runtime; they are not Safari or Firefox rendering verification.
• Runtime source attribution is best effort and depends on the target app's build/runtime metadata.
• Inspect mode is limited to trusted loopback targets such as localhost and 127.0.0.1.
• Inspect sessions and layout captures are temporary, local runtime state.

Troubleshooting

• Browser executable not found: run npx playwright install chromium in the environment that launches the MCP server.
• spawn C:\Windows\system32\cmd.exe ENOENT: install the package globally and configure your MCP client to run kaleidoscope-mcp directly.
• sourceDir must be inside...: set KALEIDOSCOPE_WORKSPACE_ROOT to the project root you want Kaleidoscope to inspect.
• Port conflicts: set KALEIDOSCOPE_SERVER_URL=http://localhost:<free-port> or stop the process using port 5000.

Privacy And Safety

• Kaleidoscope is designed for local preview and inspection workflows.
• The local API binds to 127.0.0.1 by default.
• Inspect mode is limited to loopback targets, and source reads must stay under KALEIDOSCOPE_WORKSPACE_ROOT.

License

Kaleidoscope is released under the MIT License. See LICENSE.