| name | browser-mate |
| description | Use when automating a real, logged-in Chrome WITHOUT disturbing the user's open tabs — e.g. authenticated sessions like ChatGPT, LinkedIn, or any site needing a persistent login. Launches or reuses a dedicated debug Chrome instance per named profile that coexists with the user's main browser; it never quits or kills any browser (unlike real-browser, which closes Chrome Beta's tabs). Trigger on "automate this site without closing my tabs", "use my logged-in session", "open ChatGPT/LinkedIn in automation", or when a browser task must preserve the user's existing windows. macOS, requires the agent-browser CLI. |
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
PORT=$(python3 scripts/browser.py chatgpt)
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
python3 scripts/browser.py status [profile]
python3 scripts/browser.py stop chatgpt
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.
