chrome-devtools-remote

You are operating the chrome-devtools CLI in remote mode against a chrome-devtools-mcp server that the user has running on another host. The remote server owns the browser; your job is to drive it.

When to use this skill

Trigger on any request that:

• Names a remote machine ("on the lab mac", "on host X", "on my tailnet box") and asks you to do something a browser would do
• Provides a chrome-devtools-mcp HTTPS URL (typically ending in /mcp) and asks for an interactive browser action
• Mentions environment variables CHROME_DEVTOOLS_MCP_REMOTE_URL or CHROME_DEVTOOLS_MCP_REMOTE_INSECURE

If the user wants to drive a local browser, use the regular chrome-devtools CLI (without --remote) or the mcp__chrome-devtools__* MCP tools instead.

Install (on the local box, once)

The chrome-devtools client CLI ships in the same npm package as the server. Install globally on the machine where the agent runs — not on the remote host:

npm install -g @vibebrowser/chrome-devtools-mcp
chrome-devtools --version   # should print 0.26.6 or newer

You do not install anything on the remote host — that host is whoever already serves https://.../mcp and is set up out-of-band.

Troubleshooting:

• command not found: chrome-devtools — npm's global bin isn't on PATH. Add $(npm config get prefix)/bin to PATH, or on macOS Homebrew add eval "$(brew shellenv)" to your shell rc.
• Cannot find package 'pkce-challenge' on first run — known bundling gap (issue dzianisv/chrome-devtools-mcp#17). Workaround: cd "$(npm root -g)/@vibebrowser/chrome-devtools-mcp" && npm install pkce-challenge --no-save.

Connect

Configure the endpoint once per shell session and verify connectivity before doing anything else.

export CHROME_DEVTOOLS_MCP_REMOTE_URL="https://lab.tailnet.ts.net/mcp"
chrome-devtools status --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

A healthy response prints status=ok http=200 plus a JSON body. Anything else is a hard stop — surface the error to the user instead of retrying.

If the URL is unset, ask the user once for the endpoint. Conventional shape: https:///mcp (the /mcp path is required — the bare host returns a 404).

Connection-time flags:

Once status is green, every subsequent chrome-devtools ... --remote "$URL" call reuses the same server-side tab via a sticky session id cached at ~/.cache/chrome-devtools-mcp/remote/.session.

Session model — read this before chaining commands

Each CLI invocation reuses a sticky session id stored under ~/.cache/chrome-devtools-mcp/remote/.session. This means:

• navigate_page → take_snapshot → click → take_screenshot all hit the same server-side tab. You can chain them as separate CLI calls and assume continuity.
• If the server restarts between calls, the next call transparently re-initializes against a fresh session. Tab state on the server is lost — re-navigate before assuming anything.
• To explicitly end the server-side session and free its browser context, run chrome-devtools stop --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL".

Common operations

All commands accept --output-format json to return structured output you can pipe into jq.

# Open a page
chrome-devtools navigate_page "https://example.com" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Get a structured a11y snapshot (use for finding clickable uids)
chrome-devtools take_snapshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL" --output-format json

# Click an element by uid from the snapshot
chrome-devtools click "$UID" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Fill an input
chrome-devtools fill "$UID" "value" --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Take a screenshot (saved to /tmp/<uuid>.png locally)
chrome-devtools take_screenshot --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Evaluate JS in the page — return value must be JSON-serializable
chrome-devtools evaluate_script '() => document.title' --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# Read console messages from the page
chrome-devtools list_console_messages --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

# List network requests since page load
chrome-devtools list_network_requests --remote "$CHROME_DEVTOOLS_MCP_REMOTE_URL"

Recipes

Smoke-check a deployed web app

URL="$CHROME_DEVTOOLS_MCP_REMOTE_URL"
chrome-devtools navigate_page "https://app.example.com" --remote "$URL"
chrome-devtools evaluate_script '() => ({title: document.title, ready: document.readyState})' --remote "$URL"
chrome-devtools list_console_messages --remote "$URL" --output-format json
chrome-devtools take_screenshot --remote "$URL"

If console_messages contains any level: "error" entries, surface them — they are usually the root cause of "the page looks broken" reports.

Drive a login form

chrome-devtools navigate_page "https://app.example.com/login" --remote "$URL"
chrome-devtools take_snapshot --remote "$URL" --output-format json > /tmp/snap.json
# Find the uid of the email input + password input + submit button from /tmp/snap.json
chrome-devtools fill "<email-uid>" "$LOGIN_EMAIL" --remote "$URL"
chrome-devtools fill "<password-uid>" "$LOGIN_PASSWORD" --remote "$URL"
chrome-devtools click "<submit-uid>" --remote "$URL"

Capture a CrUX-style trace

chrome-devtools performance_start_trace --remote "$URL"
chrome-devtools navigate_page "https://app.example.com" --remote "$URL"
chrome-devtools performance_stop_trace --remote "$URL" --output-format json

Output discipline

• Always print the URL of the page you navigated to so the user knows which tab they're looking at.
• For screenshots, print the path of the saved file (Saved to /tmp/.png.) — the CLI already writes that line on stdout.
• For evaluate_script, prefer --output-format json and forward only the relevant field instead of dumping the whole structuredContent envelope.
• If the user asks "what's on the page", prefer take_snapshot over take_screenshot — the snapshot is text and cheaper to reason over.

Failure modes

Don'ts

• Don't loop navigate_page to "wait for the page to load" — use wait_for with a text selector instead.
• Don't take_screenshot for every step in a chain — the user almost always wants one final screenshot, not five intermediate ones.
• Don't pass --insecure for a hosted endpoint with a real cert. It silently disables TLS for the whole CLI process.
• Don't try to start a server with --remote — that subcommand only manages local daemons.