BrowserSkill: Let AI Agents Use Your Logged-In Browser Without Stealing Your Tabs

BrowserSkill connects Cursor, Claude Code, Codex, and other shell-capable AI agents to your real browser session. Agents borrow a tab when needed, return it when done, and leave the rest of your browsing untouched.

If you’ve tried browser automation with AI agents before, you know the pattern. The agent gets a blank browser, hits a login wall, and either asks for credentials or gives up. BrowserSkill takes a different approach: it borrows a tab from the browser you’re already logged into, runs the task in a separate Agent Window, and gives the tab back when finished.

Why Browser Automation Breaks for AI Agents

Most browser automation tools hand the agent a fresh, empty browser profile. That means:

  • Every login has to be redone from scratch
  • CAPTCHAs and confirmation dialogs block progress
  • Your existing sessions, cookies, and authenticated state are useless to the agent

BrowserSkill solves this by connecting to your actual browser through a local bridge. The agent doesn’t get a blank slate. It gets access to the sites you’re already logged into, using the sessions you already have.

Key benefits:

  • Reuses real login state — Agents operate on sites where you’re already authenticated. No test accounts needed.
  • Doesn’t interrupt your work — Browser tasks run in a separate visible Agent Window. You keep using your own browser.
  • Works with any shell-capable agent — Cursor, Claude Code, Codex, OpenClaw, CodeBuddy, WorkBuddy, Pi, Hermes Agent, DeepSeek Harness. No model or framework lock-in.
  • Built-in human-in-the-loop — When the agent hits a CAPTCHA, login prompt, or confirmation dialog, it can request you take over, then continue after you’re done.

How BrowserSkill Works Under the Hood

BrowserSkill sits between your AI agent and your browser as a local bridge. Here’s the architecture:

Agent Runtime (Cursor / Claude Code / Codex / OpenClaw)
    ↓ shell: bsk ...
bsk CLI
    ↓ local IPC
bsk daemon
    ↓ 127.0.0.1 WebSocket
BrowserSkill Extension
    ↓ automation
Agent Window
    - - - → borrows tab only when requested
Your Regular Browser Windows

The agent never talks to the browser directly. It sends browser tasks through the bsk CLI. The local daemon routes requests to the extension. The extension executes them in the Agent Window.

DeepSeek Harness uses the same pipeline through a dedicated plugin: the agent calls injected browser_* tools, and the plugin handles bsk execution on its behalf.

Everything runs locally. No cloud relay, no remote browser farm.

Installation: Three Steps

You need three things: the bsk CLI, the browser extension, and the skill that teaches your agent harness how to use BrowserSkill.

Step 1: Install the bsk CLI

macOS / Linux (recommended install location: ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"

Windows (PowerShell, installs to ~/.local/bin):

irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex

The export command makes the CLI findable in your current Unix shell. If your agent runs in a separate shell session, it may need the same PATH set on every invocation, or you can use the absolute path to the installed binary. If your agent still sees an old PATH after installation, restart it.

Verify the binary in the terminal or agent environment where you’ll actually use it:

bsk --version

Step 2: Install the Browser Extension

Install BrowserSkill from your browser’s extension store:

Browser Store Link
Chrome Chrome Web Store
Microsoft Edge Edge Add-ons

For other Chromium-based browsers, install the Chrome Web Store version.

Step 3: Install the Skill

BrowserSkill ships with a skill that teaches agent harnesses how to use bsk. One-click install supports these harnesses:

Cursor, Claude Code, Codex, OpenClaw, CodeBuddy, WorkBuddy, Pi, Hermes Agent

bsk install-skill

Use Space to select harnesses, Enter to install. Run bsk install-skill --list to see internal variants and installation paths.

For non-interactive installation, specify the target harness explicitly:

bsk install-skill --harness cursor --json

You can select a harness even if it isn’t detected. Using --yes alone installs to all detected harnesses and errors out if none are found.

To install custom instructions:

bsk install-skill --harness cursor --source ./SKILL.md

Installations with an explicit --source are always treated as custom, even if the content matches the built-in skill. Existing installations are skipped by default; add --force to overwrite.

Skill auto-update behavior:

The daemon startup, session start, and doctor check installed skills. Auto-update only continues if the file content still matches what was last installed or synced. Local edits are preserved and updates are paused.

Historical installations without a content baseline are only auto-managed if they’re byte-identical to the current built-in skill. In that case, only the source marker is added; SKILL.md is not rewritten. Explicit custom installations are never auto-managed, even if content is identical.

For historical files with different content, local edits, or unrecognized source markers, doctor shows a WARN explaining why updates are paused and how to resume. These warnings don’t fail the health check (status: "warn", ok: true in --json). If another installation or sync is in progress, this sync is deferred.

To keep current instructions as an explicit custom installation:

bsk install-skill --harness cursor --source <existing-SKILL.md> --force

To restore the built-in skill and re-enable auto-update:

bsk install-skill --harness cursor --force

Without --source, this overwrites existing instructions.

Other shell-capable agent harnesses can also use BrowserSkill by manually copying skill/SKILL.md to browser-skill/SKILL.md in the appropriate skills directory. DeepSeek Harness uses a separate plugin (covered below).

Step 4: Verify the Connection

Run bsk doctor and follow the prompts. Open the extension popup to confirm it’s connected. Before testing browser operations, address any warnings and resolve failures.

If no skill is installed, doctor may still pass (that check shows N/A). Skill discovery needs separate verification.

Start a new agent session, confirm browser-skill is available in the harness, then ask it to open https://example.com and summarize the page. For harnesses that support slash commands:

/browser-skill open example.com and summarize what is on the page.

First-time verification should successfully read the page and stop the BrowserSkill session. If the skill isn’t found, check the target harness and installation path, then retry.

Sandboxed Agent Environments

If your agent sandbox recycles background processes after each command, read the sandbox configuration guide first (docs/sandboxed-agents.md).

The setup: keep the daemon alive on the host side. Inside the sandbox, connect through a shared BSK_HOME and BSK_AUTO_START=0. Standard local environments auto-start by default and need no extra configuration.

Two Browser Settings That Control Agent Behavior

The extension popup has two independent settings, both enabled by default. Settings saved in the extension have final say over all sessions.

Confirm Before Borrowing Tab Allow Human Assistance Requests Actual Behavior
On On Borrowing requires confirmation; help requests show a popup.
On Off Borrowing requires confirmation; help requests return disabled.
Off On Borrowing skips confirmation; help requests show a popup.
Off Off Borrowing skips confirmation; help requests return disabled.

Settings auto-save to the current browser profile and apply to existing and new sessions. Turning off borrow confirmation releases pending requests. Turning off human assistance ends waiting help requests as disabled.

Re-enabling either switch restores the corresponding behavior for subsequent operations, including sessions created with the deprecated --unattended flag. Completed borrows are not revoked; ended help requests do not reappear.

Allowing human assistance means request-help is available. It doesn’t mean every browser operation requires permission first. Task authorization and host approval still apply.

What Changed in 0.3.0

--unattended, tab borrow --no-confirm, and BSK_REQUEST_HELP=off no longer skip confirmation or disable human assistance. Use the extension settings instead.

These flags remain recognized for compatibility but are deprecated and cannot override extension switches. The CLI outputs an explanation when these inputs are used. The daemon also logs an explanation for inherited legacy environment settings. Scripts that relied solely on these inputs to avoid waiting now need to follow browser settings.

session start --json and session list --json return the browser’s actual interaction policy.

When Human Assistance Is Disabled

When human assistance is off, request-help returns disabled. This does not mean the user completed the operation.

The skill guides the agent to re-observe the page, use existing login state, authorized inputs, and available tools to complete authorized steps. When task authorization and host rules permit, vision-capable models can attempt graphical verification. Phone QR codes, facial verification, unreachable SMS codes, and graphical CAPTCHAs that text-only models cannot recognize can be reported as blocked.

Disabling assistance does not increase authorization, and a task cannot be marked complete or blocked solely because help is unavailable.

Preference Read Failures

When preference reading fails, the background retains existing valid values. If no valid values exist, both settings default to on. Defaults are not written back, and new sessions are not blocked. Subsequent requests retry the read; storage changes can also restore the policy.

The popup retains read error indicators and prevents saving. Write failures are not treated as success. When the browser is not connected, a connection error is returned; disabled is not fabricated locally based on command-line arguments or environment variables.

Borrow Timeout and Protocol Compatibility

tab borrow --timeout 60s only sets the confirmation wait time. It does not determine whether confirmation is needed.

Protocol 1.3 remains connection-compatible with protocols 1.0–1.2. During staged upgrades, you can still create standard sessions and borrow tabs with default wait times. The extension warns about old daemon compatibility limits, and bsk status shows protocol differences.

Custom borrow wait times require both the daemon and extension to support protocol 1.2 or higher. If unsupported, only that operation is restricted and an upgrade prompt is shown. Old daemons may still have shorter default borrow wait budgets.

The new CLI’s request-help requires daemon protocol 1.3 because old daemons may return locally without asking the browser. This restriction doesn’t disconnect the browser or affect other operations.

After the CLI, running daemon, and extension are all updated, the full setting priority described above applies. The new extension always processes requests according to saved switches. Old CLIs may return locally due to BSK_REQUEST_HELP=off before connecting to the daemon. Mixed versions preserve this historical behavior; upgrading only the extension cannot change old executable behavior.

Upgrading BrowserSkill

For standard local configurations, finish any running browser tasks before updating:

bsk update --yes

On Windows, if the update reports as staged, wait for the replacement to complete before checking bsk --version.

When installing a new version, the command restarts the running daemon with default startup configuration. If you replaced the binary through the install script, run bsk daemon restart after tasks complete to restart the existing daemon.

For custom ports, host-managed sandbox daemons, or remote servers: stop the daemon in its host environment or process manager first, run bsk update --yes --no-restart-daemon, then start it there with the original arguments and BSK_HOME. During maintenance, set BSK_AUTO_START=0 in agent commands.

Update the extension through the browser store. Development unpacked versions need to be rebuilt and reloaded. Store versions may lag behind the CLI.

Use bsk --version and bsk status to check CLI, daemon, and extension versions, then run bsk doctor. Features like long screenshots require matching versions. DSH plugins need separate updates and profile restarts.

Managed CLI skills sync at daemon startup, session start, or doctor. Local edits and custom skills are preserved. Start a new agent session to load updated instructions.

Long Screenshots

You can capture long screenshots from the extension’s Quick Actions → Long Screenshot, or ask the agent to run:

bsk screenshot --session <id> --full-page --out page.png

Default capture and encoding timeout is two minutes. For long pages, add --timeout 5m. Ctrl-C cancels; the original scroll position is restored afterward.

Requires matching CLI and extension versions. See docs/long-screenshot.md for details.

DeepSeek Harness Plugin

Using DeepSeek Harness (dsh)? BrowserSkill provides an official dsh plugin published to npm: @wxg-prc-cpg/browser-skill-dsh-plugin.

It gives the agent native browser_* tools, with the plugin calling bsk on its behalf and showing browser sessions live in the Web UI.

Install the bsk CLI and connect the browser extension first, then add the plugin to your dsh profile and start it (replace web with your profile name):

dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
dsh --profile web

The plugin ships with its own browser-skill skill, so bsk install-skill is not needed under dsh.

Installed plugins don’t auto-update. To upgrade:

dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest

Restart the profile after upgrading. Usage and configuration: packages/dsh-plugin-browserskill/README.md.

Supported Platforms

Component Support
Operating Systems macOS (Apple Silicon and Intel), Linux (x64 and ARM64), Windows x64
Browsers Chrome and Microsoft Edge officially supported; other Chromium-based browsers with extension loading usually work; Firefox planned

For Developers

The repository is a Cargo + pnpm workspace:

  • crates/bsk-cli — bsk CLI and local daemon
  • crates/bsk-protocol — Shared protocol types and JSON Schema
  • apps/extension — Browser extension
  • packages/ui and packages/i18n — Extension UI shared support, with English, Simplified Chinese, and Korean localization
  • packages/dsh-plugin-browserskill — DeepSeek Harness plugin (@wxg-prc-cpg/browser-skill-dsh-plugin)
  • evals/browser — Deterministic local pages and agent-agnostic browser capability test bench

The scroll-to primitive documentation (docs/scroll-to.md) covers CLI, protocol, and plugin entry points, plus visible area, error, and interruption semantics.

FAQ

Does BrowserSkill work with any AI agent?

Any agent that can call a shell can use BrowserSkill through the bsk CLI. It doesn’t bind to a specific model, agent framework, or harness.

Does it interfere with my normal browsing?

No. Browser tasks run in a separate visible Agent Window. Your regular browser windows are unaffected unless the agent explicitly borrows a tab, which requires confirmation by default.

Can the agent bypass the confirmation setting?

No. The confirmation toggle lives in your browser extension settings, not in a command-line flag. Deprecated flags like --unattended are recognized but cannot override extension switches.

What happens when the agent hits a CAPTCHA?

The agent can request human assistance. You take over, complete the CAPTCHA, and the agent continues. This requires the “Allow Human Assistance” setting to be on.

Is everything local?

Yes. The CLI and daemon run on your machine. The extension connects via 127.0.0.1 WebSocket. No cloud relay.

What license is BrowserSkill under?

MIT.

Get Started

# Install CLI (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh

# Install the skill for your agent harness
bsk install-skill

# Verify everything works
bsk doctor

Then ask your agent to open a page and summarize it. The agent borrows a tab, does the work, and hands it back.

Repository: github.com/Tencent/BrowserSkill

License: MIT