agent-browser-helper

agent-browser-helper

Manages a local Chrome instance with anti-detection parameters and persistent profiles. After starting Chrome, use the playwright-cli skill to operate it.

Prerequisites

• playwright-cli skill + CLI:

  npx skills add microsoft/playwright-cli@playwright-cli -g -y
  npm i -g @playwright/cli@latest
  

• A Chromium-based browser (Chrome, Edge, Brave, etc.)

If chrome.sh start outputs a warning field, follow the install instructions in that message before proceeding.

Workflow

Step 0: Ensure playwright-cli skill is installed

BEFORE doing anything, check if the playwright-cli skill is available. If not installed, STOP and tell the user to install it:

npx skills add microsoft/playwright-cli@playwright-cli -g -y

Do NOT attempt to operate the browser without the playwright-cli skill. Without it you have no command reference and WILL guess incorrectly.

Step 1: Browser selection (first-run only)

If start returns action_required: "select_browser", you MUST present the full list to the user and ask them to choose. Do NOT pick one yourself.

Example interaction:

Agent: "The following browsers were detected, please choose which one to use:

1. Google Chrome (Linux) - /usr/bin/google-chrome
2. Google Chrome (Windows) - /mnt/c/Program Files/Google/Chrome/Application/chrome.exe
3. Microsoft Edge (Windows) - /mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"

User: "Use 2"

Agent: chrome.sh set-browser 2

Then retry start. This only happens once — the choice is saved to config.

Step 2: Start Chrome

bash $SCRIPTS/chrome.sh start

Output includes cdpPort — note this value for the next step.

Step 3: Operate the browser via playwright-cli

Read the playwright-cli skill to learn how to attach to an existing browser via CDP and operate it. Pass http://localhost:<cdpPort> from Step 2 as the CDP endpoint. Do NOT guess commands — read the skill first.

Commands

$SCRIPTS = this skill's scripts/ absolute path.

start

bash $SCRIPTS/chrome.sh start                    # default profile, headed, port 9222
bash $SCRIPTS/chrome.sh start --profile work     # named profile (isolated user-data)
bash $SCRIPTS/chrome.sh start --headless         # headless (default is HEADED)
bash $SCRIPTS/chrome.sh start --port 9333        # custom CDP port

stop

bash $SCRIPTS/chrome.sh stop
bash $SCRIPTS/chrome.sh stop --profile work

status

bash $SCRIPTS/chrome.sh status

detect

Scan for installed Chromium-based browsers (Linux, macOS, Windows/WSL). Returns a numbered list for the user to choose from.

bash $SCRIPTS/chrome.sh detect

set-browser

Save the browser choice to config. Accepts an index from detect output or a direct path.

bash $SCRIPTS/chrome.sh set-browser 1            # select by index from detect
bash $SCRIPTS/chrome.sh set-browser /usr/bin/chromium  # direct path

First-run flow: If browserPath is empty, start will automatically run detect and return the list. The agent should present the list to the user, ask which browser to use, then call set-browser with the user's choice. Once configured, subsequent start calls work directly without asking again.

Profile system

Each profile has its own isolated user-data directory: ~/.agent-browser-helper/{profile}/user-data

This means:

• Cookies, localStorage, sessions persist across browser restarts
• Extensions installed in a profile stay installed
• Login state survives — no need to re-authenticate every time
• Different profiles are fully isolated (different ports, different data)

When to use named profiles:

• --profile xiaohongshu — keep XHS login separate
• --profile work — corporate SSO sessions
• --profile clean — fresh profile for testing

Important: If the user has previously logged into a site, remind them which profile contains that session. Don't start a new unnamed profile and lose their login state.

Configuration

Edit config.json in the skill directory:

{
  "browser": {
    "browserPath": "",
    "headless": false,
    "noSandbox": true,
    "defaultProfile": "default",
    "extraArgs": [
      "--disable-blink-features=AutomationControlled",
      "--disable-infobars",
      "--window-size=1280,720"
    ],
    "profiles": {
      "default": { "cdpPort": 9222 }
    }
  }
}

Browser path

Field	Description

Profile options

Field	Description	Default
cdpPort	CDP debugging port	9222
userDataDir	Custom user data directory	~/.agent-browser-helper/{profile}/user-data

extraArgs for anti-detection

Arg	Purpose	Default
--disable-blink-features=AutomationControlled	Hide navigator.webdriver	✅ on
--disable-infobars	Remove automation info bar	✅ on
--window-size=1280,720	Normal viewport (avoids 800x600 fingerprint)	✅ on
--proxy-server=http://HOST:PORT	HTTP proxy	off
--lang=zh-CN	Browser language	off
--user-agent=...	Custom User-Agent	off

Anti-detection defaults

Out of the box, this skill applies:

1. No --enable-automation — navigator.webdriver returns undefined
2. --disable-blink-features=AutomationControlled — removes CDP automation markers
3. --disable-infobars — no "Chrome is being controlled" banner
4. --window-size=1280,720 — normal desktop viewport
5. Headed mode — headless browsers have distinct fingerprints
6. Persistent profile — real cookies/history make the browser look "lived-in"
7. No Playwright/Puppeteer in launch path — no extra automation flags injected

For sites with aggressive detection (Cloudflare, DataDome), consider also adding a real User-Agent string and proxy to extraArgs.