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.

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.