browser-profiles.md

Select a specific browser profile

BrowserSkill connects to the extension installed in a browser profile. A successful connection alone does not identify the profile you intended to use. The CLI does not launch Chrome or accept Chrome's --profile-directory argument.

Bind a task to the intended profile

1. Open the required profile in Chrome. If you need to verify its directory, open chrome://version in that window and check Profile Path.
2. Open BrowserSkill's popup in that same profile and ensure it is connected.
3. Choose Copy instructions next to the current browser name and send the instructions along with your task to the agent. The copied instruction identifies the browser by its saved name and requires its extension instance ID on every new session for the task. Renaming changes the description, not the routing ID.

You can also copy the Instance ID from the popup and use it directly:

bsk browsers --json
bsk session start --browser <instance-id> --json

Replace the placeholder with the popup's instance ID, not Chrome's extension ID, profile display name or directory name. An existing, verified unique BrowserSkill label also works; labels are not populated from Chrome profile names automatically. The instruction only copies text: it does not start a session or change settings.

For a reusable human-readable selector, use the pencil beside the current browser name in the extension popup to edit and save Browser name, then confirm it appears in bsk browsers. Keep names unique among connected browsers; label matching is exact and duplicate labels are rejected as ambiguous. Saving a name briefly reconnects BrowserSkill so the daemon sees it immediately. Renaming is disabled while that browser has active tasks, so a display-name edit cannot interrupt them. You can then start a session with, for example:

bsk session start --browser "Work profile" --json

If the target is offline, reconnect BrowserSkill in that profile and retry the same selector. Do not remove --browser to get past the error: that could select another profile. A missing selector is rejected when multiple browsers are online, but automatically selects the only connected browser when just one is online.

The session remains bound to its selected instance. Opening or switching Chrome profiles does not move an existing session. Stop it with bsk session stop <id> when the task ends. Reinstalling the extension or resetting its storage can change the instance ID; verify the mapping again instead of substituting another browser. Copying a whole profile can also copy its extension storage, so instance IDs are routing identifiers, not independent proof of a filesystem path.

Incognito Agent Windows

To isolate a task from the selected profile's ordinary website login state, enable chrome://extensions → BrowserSkill → Details → Allow in incognito, then run:

bsk session start --browser <instance-id> --incognito --json

Without --incognito, sessions continue to use normal windows. Incognito starts require daemon and extension protocol 1.4 or later. Missing permission, an older peer, or a browser refusal returns an error; BrowserSkill never retries the start as a normal window. Direct extension callers can pass incognito: true to tool.session_start.

Incognito sessions create their own tabs and cannot borrow user tabs. Normal sessions also cannot borrow incognito tabs. Navigation, input and screenshots use the same tools as normal sessions.

All incognito windows in the same profile share one incognito cookie jar, including windows opened by the user and other tasks. Closing one Agent Window does not clear that shared state while another incognito window remains open. Chrome clears the incognito website data when the last incognito window closes. This is isolation from normal browsing, not a separate cookie jar per task.

Stopping a session still closes its agent-created tabs and preserves user-created tabs and protected popups. Such tabs may keep the incognito window and its browsing session alive. Downloads and BrowserSkill's own operation history follow their existing retention rules.

DeepSeek Harness

Use the verified popup instance ID in the plugin's session tool:

bsk_session({ action: "start", browser: "<verified-instance-id>" })

For an incognito Agent Window, add incognito: true to that call. The extension must have Allow in incognito enabled, and the plugin, CLI, daemon and extension must support protocol 1.4 or later; a missing permission or an older peer returns an error instead of retrying as a normal window.

Copy instructions includes this tool call alongside the CLI command. Use the DeepSeek Harness call instead of running a separate CLI session. The plugin manages its own sessions. Supply the same selector on every new session for the task, even if only one browser is connected. If the mapping is unknown or the target is offline, ask the user to confirm or reconnect it; do not retry without browser.

Scope and limitations

This is a manual profile-to-instance workflow, not automatic profile discovery or a persisted task/workspace requirement. Explicit selectors reject unavailable or ambiguous targets. Neither the CLI nor the DSH plugin can infer a profile requirement from the user's conversation if the agent omits the selector: with only one browser connected, an unqualified start can still select the wrong profile. The skill and copied instructions guide the agent; they do not enforce a binding on future calls.

Windows and macOS

The instance-selection workflow is the same on both platforms. The profile path location differs; use the value displayed by Chrome rather than guessing it. Chromium documents this check.

Several profiles can run in one Chrome browser process. Its startup command line may still name the first profile after a second profile opens, so scanning process arguments cannot prove which profile owns a connected extension. There is no need to quit all other Chrome profiles to select a connected BrowserSkill instance.