Skip to main content
Glama

boxcheck

100% local DOM geometry, CSS cascade, and layout-collision oracle (CLI + MCP) so coding agents stop shipping broken mobile UIs. Speaks raw CDP over Node 24 WebSocket with zero runtime dependencies.

License: MIT Node >=24 Zero Dependencies

boxcheck visual collision report and mobile defect breakdown


See It Catch Mobile Layout Bugs Locally (Zero Setup)

npx boxcheck --demo --json --out ./boxcheck-report.html

Spins up a built-in responsive SaaS pricing page (0 defects on 1440x900 desktop, mobile collisions on 390x844), audits it in local headless Chrome via raw CDP, prints compact deterministic collision JSON with winning CSS rules, and writes a self-contained visual SVG/PNG overlay report to ./boxcheck-report.html.


Related MCP server: art-director-mcp

Quick Start

# Audit mobile + desktop viewports
npx boxcheck audit http://localhost:3000 --vp 390x844,1440x900 --json

# Generate visual SVG/PNG collision overlay report
npx boxcheck audit http://localhost:3000 --vp 390x844 --out ./report.html

# Save lightweight git-committable JSON geometry baselines (.boxcheck/baselines/)
npx boxcheck snap http://localhost:3000

# Diff live geometry against baseline (flags unintended >2px shifts/resizes)
npx boxcheck diff http://localhost:3000 --fail-on-defects

Connect to Your Coding Agent (Stdio MCP)

boxcheck mcp exposes three lean tools (boxcheck_audit, boxcheck_snap, boxcheck_diff) returning compact deterministic JSON instead of giant accessibility tree dumps.

Antigravity / Cursor / Claude Code / Codex / OpenCode

{
  "mcpServers": {
    "boxcheck": {
      "command": "npx",
      "args": ["-y", "boxcheck", "mcp"]
    }
  }
}

What boxcheck Detects (with Built-In False-Positive Shield)

Defect Kind

Deterministic Condition

False-Positive Shield

OVERLAP

Non-ancestor content/interactive siblings intersect >=4px on both axes (>=24px²)

Ignores ancestor-descendant pairs, pointer-events: none, aria-hidden, inert, sticky/fixed layers, small corner badges, <4px subpixel jitter

H_OVERFLOW

Page scrollWidth > clientWidth + protruding elements past viewport edge

Skips intentional overflow-x: auto/scroll/hidden containers and their scrollable children; deduplicates ancestor/descendant chains

TEXT_CLIPPED

Text exceeds overflow: hidden/clip box by >=6px

Ignores intentional text-overflow: ellipsis and -webkit-line-clamp truncation

OFF_SCREEN

Visible interactive element pushed >50% outside horizontal viewport

Ignores elements inside horizontal scroll containers, clipped/hidden/zero-opacity nodes

OCCLUDED

elementFromPoint(cx, cy) hits an unrelated higher z-index blocker

Ignores self, descendants, ancestors, and elements clipped out by scroll ancestors

Each defect is enriched via CDP CSS.getMatchedStylesForNode with the exact deduplicated winning_css rule so your coding agent fixes the root CSS line directly.


Honest Comparison

Feature

boxcheck

Playwright MCP

agent-browser

Chromatic / Percy

Install & Footprint

~52 kB tarball, 0 runtime deps, uses system Chrome/Edge

Heavy browser bundle

Node + browser

Paid cloud SaaS + CI

Output size per layout check

Compact JSON capped for small agent context budgets

Large a11y trees / PNGs

Navigation-focused refs

N/A (human PR review)

Deterministic overlap / overflow / occlusion math + winning_css

Yes

No

No

Pixel diff only

Git-committable JSON geometry baselines

Yes (tiny .json)

No

No

Cloud PNG storage

Where competitors win

(Chromium-only layout oracle)

Full interactive clicking, form filling, E2E scripting

Multi-step web navigation

Cross-browser Safari/Firefox cloud visual approval workflows


Architecture

flowchart LR
    Agent["Coding Agent / CLI\n(Antigravity · Claude Code · Codex · Cursor)"] -->|"CLI or Stdio MCP"| Core["boxcheck\n0 runtime deps · Node 24"]
    Core -->|"Raw CDP over native WebSocket"| Chrome["Headless Chrome / Edge / Chromium\n(isolated temp profile, auto-cleaned)"]
    Chrome -->|"Rects + Computed Styles + elementFromPoint"| Detector["Deterministic Collision Math\n+ False-Positive Shield"]
    Chrome -->|"CSS.getMatchedStylesForNode"| Cascade["Winning CSS Attribution"]
    Detector --> Output["Compact JSON · Baselines · SVG/PNG Overlay"]
    Cascade --> Output

Local Agent Reliability Suite

  • kvdiff: Zero-code local proxy that pinpoints the exact UTF-8 byte breaking your LLM prompt cache (Anthropic, OpenAI, Gemini/Antigravity, llama.cpp/vLLM).

  • boxcheck (this repo): Local DOM geometry & CSS collision oracle (CLI + MCP).

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables CSS layout verification and debugging by extracting deterministic, diffable rendered layout from a browser, allowing agents to inspect, explain, and diff CSS changes.
      14 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides coding agents with local tools to inspect project UI inventories, propose and compare visual direction boards, compile versioned design contracts and DTCG tokens, retrieve section-specific blueprints, and audit running interfaces with browser evidence including screenshots, accessibility findings, and overflow measurements.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables cross-browser mobile-first responsive layout auditing and browser automation, including overflow detection, tap target checks, viewport/media query introspection, and screenshot matrices via MCP.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents and CI to verify rendered web UIs against design token usage, layout constraints, and accessibility rules, returning concise pass/fail verdicts with actionable findings.
      12 npm
      MIT