Use dedicated profiles - Do not attach to the user's daily Chrome profile. Chrome 136+ blocks remote debugging against the default data directory, and attaching to a real daily profile exposes too much user state.
Use named profiles - Prefer clear names such as work, personal, github-debug, or client-a.
Never inspect credentials - Do not read cookies, Login Data, browser history, local storage, or profile database contents unless the user explicitly requests a safe redacted diagnostic.
Delete only managed profiles - Only delete profiles inside ~/.agents/chrome-profiles that contain this skill's .vp-chrome-profile marker.
Warn about open debug ports - While a Chrome remote debugging port is open, local processes can inspect and control that browser session.
Keep attach mode out of the main path - --autoConnect and existing browser attach flows require explicit user-side setup and are not the supported lifecycle path for this skill.

Helper

Resolve scripts/chrome-profilectl from this skill directory and use it as the source of truth for profile lifecycle operations.

scripts/chrome-profilectl doctor
scripts/chrome-profilectl list
scripts/chrome-profilectl create work
scripts/chrome-profilectl launch work --port 9344 --url https://example.com
scripts/chrome-profilectl mcp-args work --port 9344
scripts/chrome-profilectl status --port 9344
scripts/chrome-profilectl delete work --yes

The default root is always ~/.agents/chrome-profiles. For tests, set HOME to a temporary directory instead of adding a custom root.

Use --headless only for mechanical endpoint checks. User login and debugging sessions should be visible Chrome windows so the user can see what the agent can inspect.

Workflow

1. Inspect Existing Profiles

Run:

scripts/chrome-profilectl doctor
scripts/chrome-profilectl list

If no suitable profile exists, ask for the intended profile name and create it:

scripts/chrome-profilectl create <name>

2. Launch For User Login

Open a visible Chrome window with a dedicated user data directory:

scripts/chrome-profilectl launch <name> --port 9344 --url https://example.com

Ask the user to complete any login or setup inside that window. Do not ask the user to paste session tokens, cookies, passwords, or other secrets into chat.

3. Connect Chrome DevTools MCP

Use the browser URL printed by launch, or generate MCP args:

scripts/chrome-profilectl mcp-args <name> --port 9344

For MCP client configuration, pass --browser-url=http://127.0.0.1:<port> to chrome-devtools-mcp@latest. Prefer --no-usage-statistics unless the user explicitly wants the upstream default.

4. Verify Before Acting

Before claiming a profile is usable:

scripts/chrome-profilectl status --port 9344

Then use Chrome DevTools MCP to list pages and verify the expected title or URL. Only inspect page content needed for the user's task.

5. Delete Safely

Deletion is destructive. Before deleting, show the profile name and path and get explicit confirmation. Then run:

scripts/chrome-profilectl delete <name> --yes

If the profile lacks a .vp-chrome-profile marker, stop. Do not bypass this by removing files manually. If Chrome is still using the profile, close that Chrome window first.

Migration Notes

If the user wants to move an existing profile such as a Hermes profile, first close every Chrome process using it. Copy the profile directory into ~/.agents/chrome-profiles/<name>, then run:

scripts/chrome-profilectl adopt <name> --yes

Adopt only profiles already inside ~/.agents/chrome-profiles; never adopt the daily Chrome data directory.

Common Mistakes

Using --isolated for login work: that creates a temporary profile and loses state when Chrome closes.
Connecting to 127.0.0.1:9222 by habit: avoid the default Chrome debug port unless the user intentionally chose it and you verified the endpoint is the dedicated managed profile, not a daily Chrome session.
Launching Chrome directly on macOS: use the helper; macOS GUI sessions are more reliable through open -na "Google Chrome" --args.
Using a temporary HOME for visible login: macOS may show a Keychain prompt. Use the real user HOME for visible login, or --headless only for mechanical endpoint checks.
Treating extension targets as user pages: filter DevTools pages by type: "page" and expected URL/title.

vp-chrome-profiles

Chrome Profiles For Agents

Core Rules