Agentic | Caliper

Agent

Connect your browser to AI agents for high-precision design auditing and automated layout verification.

Installation

Step 1: Install the package

pnpm install @oyerinde/caliper

* Optional if you're only using the global CDN script.

Step 2: Initialize in your project

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {process.env.NODE_ENV === "development" && (
          <Script
             src="https://unpkg.com/@oyerinde/caliper/dist/index.global.js"
             data-config={JSON.stringify({ 
               bridge: { enabled: true } 
             })}
             strategy="afterInteractive"
          />
        )}
        {children}
      </body>
    </html>
  );
}

Configuration

export interface AgentBridgeConfig {
  enabled?: boolean;    // Toggle bridge (default: false)
  wsPort?: number;     // WebSocket port (default: 9876)
  onStateChange?: (state: CaliperAgentState) => void; // State callback (ESM)
  onStateChangeGlobal?: string; // Global function name (IIFE/CDN)
}

How to Use

Step 1: Setup Bridge

Complete the Installation section to inject the Caliper Bridge into your local development environment.

Step 2: Connect Agent

Configure the MCP Server in your AI agent's settings. Once connected, the agent will have passive visibility into your active tab.

Step 3: Handoff Selection

Use the Caliper UI to select an element, then use shortcuts to copy its metadata and paste it directly into your IDE or TUI chat:

Right-Click Selection — Copy the full JSON Fingerprint for a stable agent handoff.
Shift + Right-Click — Copy the specific data-caliper-agent-id to target a single element.

Stable Selectors

AI agents often need to rediscover elements after triggering code changes. While Caliper uses coordinate hit-testing as a fallback, you can ensure 100% reliability by adding stable markers to mission-critical components:

<div {...caliperProps("main-cta")}>Click Me</div>

MCP Server

The Model Context Protocol (MCP) server acts as a relay between your browser (the Bridge) and agentic IDEs like Cursor, Claude Code, or Antigravity.

Setup

Add to your mcp.json or use the UI settings:

{
  "mcpServers": {
    "caliper": {
      "command": "npx",
      "args": [
        "-y",
        "@oyerinde/caliper",
        "--port",
        "9876"
      ]
    }
  }
}

Core Tools

The MCP server exposes these tools to agents for interactive auditing:

Tool	Function
`caliper_list_tabs`	List all browser tabs currently connected to the bridge.
`caliper_switch_tab`	Switch targeting to a specific browser tab.
`caliper_inspect`	Full geometry, z-index, and computed visibility of an element.
`caliper_measure`	High-precision distance calculation between two elements.
`caliper_walk_dom`	Inspect the DOM hierarchy (parents/children) of a specific element.
`caliper_walk_and_measure`	Capture precise measurements and styles for a component and its children.
`caliper_get_context`	Comprehensive window, viewport, and accessibility metrics.
`caliper_check_contrast`	WCAG 2.1 contrast ratio check between foreground and background.
`caliper_delta_e`	Perceptual color difference check between two colors.
`caliper_clear`	Reset all active measurements and guides in the UI.

Resources

Agents can subscribe to these resources for real-time state observation:

Resource	Description
`caliper://tabs`	Live list of all connected browser windows/tabs.
`caliper://state`	Real-time passive observation of the active tab. Includes selection metadata, measurement results, and stable JSON Fingerprints that allow agents to immediately "hand-off" manual focus to inspection tools (like `caliper_inspect`).

Agent Prompts

Built-in playbooks that guide agents through complex design reconciliation tasks:

Prompt	Description
`caliper-selector-audit`	A phase-based workflow from source discovery to precision styling fix.
`caliper-selectors-compare`	Compare a "reference" element with a "target" to debug inconsistencies.