relay-inspect

<img src="logo.svg" width="128" height="128" alt="Relay Inspect">

Stop copying and pasting console logs, server errors and screenshots into your CLI. Relay Inspect gives your AI coding agent direct access to your browser—so it can see what you see, verify its own changes, and debug without asking you to copy and paste.

Relay Inspect is a lightweight tool for designers and engineers who want to spend more time building and less time debugging.

                                                    ┌─ Chrome (CDP over WebSocket)
AI Coding Agent  ←→  Relay Inspect (MCP over stdio) ─┤
                                                    └─ Dev Servers (child processes)

Relay Inspect is a bridge between the Chrome DevTools Protocol, your dev server and your agent. It exposes browser state as MCP tools—console output, network requests, DOM queries and screenshots. Your agent edits code, the dev server hot reloads, and the agent verifies the result itself.

Looking for annotations? The browser annotation overlay has moved to its own package: Annoku.

Why Relay Inspect over Chrome DevTools MCP?

Google's Chrome DevTools MCP is a full browser automation tool—it clicks buttons, fills forms, runs Lighthouse audits, and scripts interactions. Relay Inspect gives agents continuous visibility while they work, so mistakes get caught in the moment, not at the end.

• Gives agents eyes. Real-time access to console output, network requests, and DOM state — so your agent sees what's happening as it happens, not after it's already moved on.
• Tight feedback loop. The edit → reload → verify cycle happens in a single turn. Your agent makes a change, waits for the dev server to reload, and immediately confirms it worked—without additional back-and-forth.
• Focused tools, fewer wrong turns. A handful of purpose-built tools means your agent reaches for the right one rather than thrashing through a broad API surface. Less noise, more signal.
• Zero overhead, zero telemetry. Connects lazily on the first tool call—no Puppeteer, no phoning home. Nothing runs until your agent needs it.

Tools

Your agent gets access to the following tools automatically via MCP:

Browser Inspection

Tool	Description	Key Parameters
evaluate_js	Execute a JavaScript expression in the browser and return the result	expression (string)
get_console_logs	Return buffered console output (logs, warnings, errors)	clear (bool, default: true)
get_network_requests	Return captured network requests and responses	filter (URL substring), clear (bool, default: true)
get_network_request_detail	Get full request/response body for a specific network request	requestId (string, from get_network_requests)
get_elements	Query the DOM with a CSS selector and return matching elements' outer HTML	selector (string), limit (number, default: 10)
take_screenshot	Capture a screenshot of the current page	format (png/jpeg, default: png), quality (0-100, jpeg only)

Page Control

Tool	Description	Key Parameters
reload_page	Reload the current page (optionally bypass cache)	ignoreCache (bool, default: false)
wait_and_check	Wait N seconds then return new console output captured during the wait	seconds (number, default: 2)
connect_to_page	Switch to a specific Chrome page target by ID or URL match	id (string) OR urlPattern (string), waitForMs (number)
navigate_to	Navigate the current page to a new URL	url (string)

Server Management

Tool	Description	Key Parameters
start_server	Start a dev server or background process and capture its output	id (string), command (string), args (string[]), cwd (string), env (object), optional urlPattern + connectWaitForMs
get_server_logs	Read stdout/stderr output from a managed server process	id (string), clear (bool, default: true)
stop_server	Stop a running managed server process	id (string)
list_servers	List all managed server processes and their status	—

Diagnostics

Tool	Description	Key Parameters
check_connection	Check Chrome connection status and diagnose issues (does not auto-launch)	—

Setup

Prerequisites

• Node.js 20+
• Chrome (or any Chromium-based browser)

Add to your MCP client

No install required — npx downloads and runs the package on first use.

Claude Code — add to .mcp.json or .claude/settings.json:

{
  "mcpServers": {
    "relay-inspect": {
      "command": "npx",
      "args": ["-y", "relay-inspect"]
    }
  }
}

Codex CLI:

codex mcp add relay-inspect -- npx -y relay-inspect

opencode — add to opencode.json:

{
  "mcp": {
    "relay-inspect": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "relay-inspect"]
    }
  }
}

Chrome is auto-launched on first tool call if it isn't already running. To disable this or customize behavior, see Configuration below.

Configuration

Environment Variable	Default	Description
CHROME_DEBUG_PORT	9222	Chrome debugging port
CHROME_DEBUG_HOST	localhost	Chrome debugging host
CHROME_AUTO_LAUNCH	true	Auto-launch Chrome if not already running
CHROME_PATH	(auto-detect)	Override Chrome/Chromium executable path
CHROME_LAUNCH_URL	(none)	URL to open when Chrome is auto-launched (e.g. http://localhost:1420)
CDP_WS_URL	(none)	Connect directly to a CDP WebSocket URL, skipping Chrome discovery
CONSOLE_BUFFER_SIZE	500	Max console entries to buffer
NETWORK_BUFFER_SIZE	200	Max network requests to buffer
SERVER_LOG_BUFFER_SIZE	1000	Max log entries per managed server

If Chrome is already running with --remote-debugging-port, Relay Inspect will connect to it directly without launching a new instance.

Development

git clone https://github.com/samsolomon/relay-inspect.git
cd relay-inspect
npm install

npm run dev    # Run with tsx (auto-recompile)
npm run build  # Build with tsup
npm start      # Run the built bundle
npm test       # Run tests with vitest

For detailed architecture, conventions, and CDP implementation notes, see CLAUDE.md.