Browser Automation

Browser Automation

Preferred Option: agent-browser

Use agent-browser for web automation. Activate the agent-browser skill before the first command.

Engine Selection

Use --engine lightpanda by default. It is ~10x faster and uses ~16x less memory than Chrome.

Fall back to the default Chrome engine when Lightpanda fails or crashes on the target site:

# Default: use Lightpanda
agent-browser --engine lightpanda open <url>

# Fallback: Chrome (omit --engine)
agent-browser open <url>

When authentication or headed mode is needed, connect to the user's running Google Chrome instead of launching a new Chrome engine. See Headed Mode: Connect to Chrome below.

Headed Mode: Connect to Chrome

Connect to the user's Google Chrome over CDP when authentication or headed mode is needed. This attaches to the real default profile (~/Library/Application Support/Google/Chrome/Default), so installed extensions such as 1Password and existing login state are available.

One-time setup: open chrome://inspect/#remote-debugging in Chrome and enable "Allow remote debugging for this browser instance" (requires Chrome 144+). The setting persists in Local State under devtools.remote_debugging.user-enabled, and Chrome then listens on port 9222 on every normal launch.

Steps:

1. Make sure Chrome is running. Launch it normally — do not pass --remote-debugging-port.

2. Connect to the GUID-less browser endpoint, and open a new tab before the first navigation so the user's existing tabs stay untouched:

   agent-browser --cdp "ws://127.0.0.1:9222/devtools/browser" tab new
   agent-browser --cdp "ws://127.0.0.1:9222/devtools/browser" open <url>
   

Start every new task with tab new. Never navigate a tab the user already had open, and keep working in the tab you created for the rest of the task. tab list shows which tab is active (→).

Constraints to respect:

• Chrome 136+ ignores --remote-debugging-port and --remote-debugging-pipe whenever the data directory is the default one, and prints DevTools remote debugging requires a non-default data directory. Passing a path that resolves to the default directory (trailing /., a symlink) does not bypass the check, because Chrome normalizes the path first.
• Pass the WebSocket URL, not --cdp 9222. In this mode Chrome serves only the browser WebSocket; every /json/* HTTP endpoint returns 404, so port-only discovery times out.
• --auto-connect works only while ~/Library/Application Support/Google/Chrome/DevToolsActivePort exists. That file disappears at times even though Chrome keeps listening on 9222, so prefer the explicit WebSocket URL.
• Never launch Chrome with a --user-data-dir that resolves to the default directory. Chrome treats the profile as tampered, resets its protected preferences, and uninstalls every extension in that profile. Recovering needs a backup.
• Do not use --profile Default to reach the real profile. agent-browser launches its bundled Chrome for Testing with a temporary user data directory, so extensions and login state are absent.
• Run agent-browser close --all only to clear a stale daemon holding Invalid CDP target errors. It can also close the connected Chrome window, so relaunch Chrome afterwards.
• While remote debugging is enabled, any local process can drive the browser and read its cookies. Keep it on only on a trusted machine.