Connect your coding agent to your Chrome

The tracker never touches a browser. Filling in directory forms is your coding agent’s job, and for that it needs a browser integration that drives a Chrome you can see and supervise. The kit’s BROWSER-SETUP.md describes two ways to establish that connection; this guide summarizes both, the macOS permissions that may come up, and the smoke check that tells you the connection is real. The principle throughout: one agent, one product, one assigned tab, one long-lived connection per batch.

Mode A: connect the Chrome you already use

This mode needs Chrome 144 or newer.

1. Check chrome://version, then open chrome://inspect/#remote-debugging in the Chrome instance you want the agent to use and enable remote debugging there. If that control is missing, do not hunt for a hidden flag — use mode B instead.
2. Configure your agent’s MCP integration to run Chrome DevTools MCP with --autoConnect. As a generic MCP server definition it looks like this; your agent’s config file and format may differ, so follow its own setup UI:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--no-usage-statistics", "--no-performance-crux"]
    }
  }
}

3. Trigger a harmless browser action from the agent and approve Chrome’s connection prompt in the intended window. A running MCP process proves nothing by itself; a visible tab that moves does.

If npx is missing, install Node.js. The first call downloads the package; once things work, pin the version you tested. Because this integration controls an authenticated browser, close unrelated sensitive tabs first, never copy the profile to another machine, and never commit cookies. If your agent already has a working browser integration, keep it.

Mode B: a dedicated local CDP profile

Some integrations want an HTTP endpoint speaking the Chrome DevTools Protocol rather than auto-connect. For those, launch a separate Chrome with its own user-data directory inside your private workspace. On macOS:

mkdir -p .browser/chrome
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.browser/chrome" about:blank

On Windows (PowerShell), from your private workspace:

$chrome = Join-Path $env:ProgramFiles "Google/Chrome/Application/chrome.exe"
if (!(Test-Path $chrome)) { $chrome = Join-Path ${env:ProgramFiles(x86)} "Google/Chrome/Application/chrome.exe" }
if (!(Test-Path $chrome)) { $chrome = Join-Path $env:LOCALAPPDATA "Google/Chrome/Application/chrome.exe" }
$profile = Join-Path (Get-Location) ".browser/chrome"
& $chrome --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 "--user-data-dir=$profile" about:blank

On Linux, substitute the installed Chrome binary. Sign in to the directory, Google and mailbox accounts you need in that window yourself. The separate directory is not optional: since Chrome 136 the legacy debugging flags are ignored for the default profile. In the MCP config, replace --autoConnect with --browserUrl=http://127.0.0.1:9222; never combine the two modes.

Keep the port local: never expose it, tunnel it or reuse somebody else’s endpoint, and check the listener is bound to 127.0.0.1. Close this Chrome when the session ends; the profile keeps your sign-ins for next time. If 9222 is taken, find out which program holds it — do not kill unrelated browsers or delete profile locks to force a connection.

macOS permissions, only where needed

A CDP-only connection usually needs no extra permissions. If your agent clicks natively or uses AppleScript, macOS will ask under System Settings → Privacy & Security: Automation for the host app to control Chrome, Accessibility for native keyboard and mouse input, Screen Recording only if the integration captures the screen. Approve the actual host application (terminal, editor or agent app), and expect Chrome’s own remote-debugging approval to recur after reconnects — it is a separate control, and no setup can promise “allow once forever”.

The smoke check before any submission

Before the agent touches a real form, ask it to open a fresh blank tab, navigate to a public directory homepage, read the main heading and tell you which tab it used. Watch the same window. Then sign in to a target directory and have the agent inspect the account menu for the correct identity: completing OAuth is not proof of being logged in at the destination. Record only pass/fail and a non-sensitive note in onboarding.json or SESSION.md, never a browser transcript.

For forms, the rules are the ones a careful human would use: read the current labels before locating fields, fill approved values, blur and read back, check character counters, and never treat a successful tool call as proof that the page saved.

When something goes wrong

The kit ships a troubleshooting table; the cases that come up most often are:

• The wrong Chrome window moves — stop, verify the selected instance and connection mode.
• A prompt appears on every action — the tool is probably restarting per call; reuse one connection.
• OAuth succeeds but the site is anonymous — inspect the destination account before submitting anything.
• CAPTCHA or 2FA — you complete it; the agent records prepared_needs_human and does not attempt evasion.
• Timeout after Submit — search the directory’s dashboard and your product name first; a timeout describes the browser, not the server.

How this compares to a standalone browser agent is covered in the three-ways article; per-agent setup lives on the Claude Code, Codex and Cursor pages.