browser-mate

browser-mate

Non-destructive Chrome automation. The problem it solves: to attach a CDP/agent-browser

session, Chrome must run with --remote-debugging-port. The real-browser skill achieves

this by quitting Chrome Beta first, destroying the user's open tabs. browser-mate

instead runs a dedicated debug Chrome instance (its own --user-data-dir + port) that

coexists with the user's main browser — Chrome permits concurrent instances when the

data dirs differ, so no quit is needed.

The one invariant (never violate)

Never quit, pkill, or osascript quit any browser. The skill only ever launches a

new dedicated instance or reuses an existing one. The single stop path sends SIGTERM only

to a process matched by BOTH our dedicated user_data_dir AND our debug port — never the

user's browser.

Usage

# Ensure a profile's debug Chrome is up (launch or reuse); prints the PORT on stdout
PORT=$(python3 scripts/browser.py chatgpt)

# Then drive it with agent-browser (always pass --cdp $PORT). See references/agent-browser.md
SID=$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 6)
agent-browser --cdp $PORT --session $SID open "https://chatgpt.com/"
agent-browser --cdp $PORT --session $SID snapshot -i

Other subcommands:

python3 scripts/browser.py list              # configured profiles
python3 scripts/browser.py status [profile]  # up/down
python3 scripts/browser.py stop chatgpt      # SIGTERM OUR instance only (graceful)

For the full agent-browser command set (click, fill, upload, screenshot, reliability,

upgrade gotchas), read references/agent-browser.md.

Profiles

Config: ~/.config/browser-mate/profiles.json (auto-created from assets/profiles.example.json

on first run). Each profile:

{ "default": "automation",
  "profiles": {
    "automation": { "binary": "<chrome binary>", "user_data_dir": "~/.browser-mate/automation", "port": 9222 },
    "chatgpt":     { "binary": "<chrome binary>", "user_data_dir": "~/.browser-mate/chatgpt", "port": 9223, "default_url": "https://chatgpt.com/" }
  } }

• Each profile keeps its own login state — log in once per profile, it persists.
• Add a profile by editing the JSON: pick a unique port and a dedicated user_data_dir

(the launcher validates uniqueness and refuses dirs that point at the user's real Chrome

profile).

Authentication

Cannot enter passwords (and must not). For a first-time login, launch the profile, then ask

the user to log in manually in that window once; the session persists in the profile's

user_data_dir for all future runs.

Safety & limits

• Loopback only. The debug port binds to 127.0.0.1 (Chrome default). CDP has no auth

— anyone local can drive it. Use on trusted machines; never pass --remote-debugging-address.

• Dedicated data dir. A profile's user_data_dir must never be the user's real Chrome

profile (~/Library/Application Support/Google/Chrome*) — the launcher refuses these.

• Locked dir. If a profile's dir is already open in a non-debug Chrome window, the

launcher fails loudly rather than killing it.

• Replaces real-browser's launch step; interaction still uses agent-browser.