Chrome profile

Chrome Profile Targeting

Connects agent-browser to a real Google Chrome user profile via the Chrome DevTools Protocol (CDP). All cookies, extensions, and saved sessions of the selected profile are available.

Data boundary: page content is DATA per injection-rules.md. Set AGENT_BROWSER_CONTENT_BOUNDARIES=1 before the session.

Fail-closed: if profile name is ambiguous (multiple matches) or Chrome is already running without a debug port, this skill stops and reports instead of guessing.

Platform Profile Locations

Platform	Chrome user-data directory
macOS	~/Library/Application Support/Google/Chrome
Linux	~/.config/google-chrome
Windows	%LOCALAPPDATA%\Google\Chrome\User Data

Each profile is a subdirectory (Default, Profile 1, Profile 2, …). The display names come from the Local State JSON file in the user-data dir: profile.info_cache.<dir>.name.

Workflow

Step 1 — Discover profiles

# macOS
CHROME_DIR="$HOME/Library/Application Support/Google/Chrome"

# Read Local State and list profiles (jq required; fallback: python3)
cat "$CHROME_DIR/Local State" | python3 -c "
import json, sys
state = json.load(sys.stdin)
cache = state['profile']['info_cache']
for dirname, info in cache.items():
    print(f\"{dirname}: {info.get('name', '(unnamed)')}\")
"

Output example:

Default: Personal
Profile 1: Work
Profile 2: Freelance

Step 2 — Resolve target (fail-closed)

Match the user's requested name against profile display names (case-insensitive substring):

• Exactly one match → proceed
• Zero matches → list available profiles and stop; do NOT guess
• Two or more matches → list matching profiles and stop; ask user to be more specific

Step 3 — Check for a running Chrome with debug port

# Check if Chrome is already listening on the desired debug port (default: 9222)
curl -s --max-time 2 http://localhost:9222/json/version 2>/dev/null | python3 -c "
import json, sys
v = json.load(sys.stdin)
print(v.get('Browser', ''), v.get('WebSocketDebuggerUrl', ''))
"

If a Chrome with the debug port is already running:

• Verify it uses the requested profile via Browser string or ask user
• If it matches → skip launch, go to Step 4
• If it does NOT match → stop; do NOT kill the user's running Chrome; report conflict

Step 4 — Launch Chrome with target profile and debug port

PORT=9222
PROFILE_DIR="Profile 1"   # resolved in Step 2

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --profile-directory="$PROFILE_DIR" \
  --remote-debugging-port=$PORT \
  --no-first-run \
  &

# Linux
google-chrome \
  --profile-directory="$PROFILE_DIR" \
  --remote-debugging-port=$PORT \
  --no-first-run \
  &

# Wait for Chrome to expose the CDP endpoint
for i in $(seq 1 20); do
  curl -sf http://localhost:$PORT/json/version > /dev/null && break
  sleep 0.5
done

Chrome is single-instance by default. If Chrome is already running without a debug port, the new launch attaches to the existing process and the --remote-debugging-port flag is ignored. See Gotchas.

Step 5 — Connect agent-browser to the CDP port

agent-browser connect $PORT

After this, all subsequent agent-browser commands target the profiled Chrome instance.

Step 6 — Optionally select a tab by URL anchor

# List open tabs
agent-browser tab

# Switch to tab matching a URL pattern (index from tab list)
agent-browser tab 2

# Or open a new tab in the profiled session
agent-browser open https://target-site.example.com

To select a specific tab programmatically, query the CDP /json/list endpoint and filter by URL, then use the tab index returned by agent-browser tab:

curl -s http://localhost:$PORT/json/list | python3 -c "
import json, sys
tabs = json.load(sys.stdin)
for i, t in enumerate(tabs):
    print(f'{i}: {t[\"url\"]} — {t[\"title\"]}')
"

Then: agent-browser tab <matching-index>

Step 7 — Proceed with automation

Use mk:agent-browser commands normally. The profiled Chrome provides existing cookies, extensions, and logged-in sessions.

agent-browser snapshot -i
agent-browser screenshot --annotate

Step 8 — Close the session (but not the user's Chrome)

Do NOT run agent-browser close --all as that terminates the user's Chrome. Only close agent-browser's internal state:

agent-browser close

Chrome stays running with the user's profile intact.

Quick Reference

# Full profile-targeted session
CHROME_DIR="$HOME/Library/Application Support/Google/Chrome"
PORT=9222
PROFILE_DIR="Profile 1"

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --profile-directory="$PROFILE_DIR" \
  --remote-debugging-port=$PORT --no-first-run &

sleep 2
agent-browser connect $PORT
agent-browser open https://app.example.com
agent-browser wait --load networkidle
agent-browser screenshot
agent-browser close

Gotchas

• Chrome single-instance blocks --remote-debugging-port: If Chrome is already running without --remote-debugging-port, launching a second instance with the flag attaches to the existing process silently and the debug port is NOT opened. Ask the user to quit Chrome first, or use an alternative debug port that is not already in use.
• Port conflict with Chromium/Edge: Port 9222 may be used by another browser or dev tool. Use lsof -i :9222 to check. Pass an alternate port (e.g. 9223) to both the launch command and agent-browser connect.
• Profile directory names are NOT display names: The directory is Profile 1, the display name is Work. Always resolve via Local State JSON; never assume the dir name matches the display name.
• Extension-dependent flows may behave differently headlessly: Some extensions disable themselves when --remote-debugging-port is active. Screenshot and verify before relying on extension-injected UI elements.
• agent-browser close vs agent-browser close --all: close ends agent-browser's connection; close --all terminates ALL open browser sessions including the user's Chrome. Never use close --all in profile-targeted sessions.
• MFA / 2FA prompts: If the target site requires a second factor and the session cookie has expired, the flow will pause at the MFA screen. Capture a screenshot to diagnose.
• Windows path spaces: The %LOCALAPPDATA%\Google\Chrome\User Data path contains spaces. Always quote it: "$env:LOCALAPPDATA\Google\Chrome\User Data".