Tencent/BrowserSkill

Let AI agents work in your logged-in browser while you keep working.

English · 中文

Quick start · Website debugging · DSH plugin · Documentation · Changelog

BrowserSkill connects your AI agent to Chrome or Microsoft Edge, using the accounts you are already signed into. Ask it to read pages, fill forms, work through a website, capture a long screenshot, or investigate a failing request. Tasks run in a separate, visible Agent Window; an existing tab can be explicitly borrowed and returned when the task ends.

Use the bsk CLI with Cursor, Claude Code, Codex, OpenClaw, CodeBuddy, WorkBuddy, Pi, Hermes Agent, or another shell-capable agent. DeepSeek Harness has a dedicated plugin with native browser tools and task previews. You choose the agent and model; BrowserSkill provides the browser connection.

Watch a browser task in action:

For local automation, you need an AI agent + the bsk CLI + the browser extension. The CLI includes the background daemon. The skill teaches your agent how to use it.

Send this to your agent:

Set up browser-skill on this machine by following https://raw.githubusercontent.com/Tencent/BrowserSkill/main/AGENT_INSTALL.md

The guide covers CLI installation, the correct skill or DSH plugin, connection checks, and a first browser task. You will still need to install the extension in the browser you want to use:

Install for Chrome · Install for Edge

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

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

bsk --version

bsk install-skill

bsk install-skill --harness cursor --json

bsk doctor

Once connected, ask your agent:

Use browser-skill to open https://example.com, summarize the page, and end the browser session when finished.

The agent opens its own window in the background, reads the page, returns the summary, and stops its task. External links or manually created tabs that land in the task window are moved to your most recently used normal window; a user window is created if none remain. Routing happens after tab creation, so a tab may briefly appear in the task window. Page-opened tabs and human assistance or recording are preserved. Harnesses that support skill slash commands can also use /browser-skill.

Chrome can still activate a window when a page opens a native popup. For observed task popups, the extension restores the previous Chrome window or minimized state if you have not switched windows. Chrome's public extension APIs cannot guarantee zero transient activation or restore focus to another application.

bsk session start --json

bsk navigate https://example.com --session <id>
bsk observe --session <id>
bsk screenshot --session <id> --out example.png
bsk session stop <id>

In WorkBuddy/CodeBuddy, or hosts that reap command children, the agent should reuse an existing daemon or run bsk daemon start --foreground in a managed background task, then verify it from a separate tool call. Follow the host setup guide for shared BSK_HOME, BSK_AUTO_START=0, and the independent-terminal fallback when the host cannot keep a task alive.

The DSH plugin adds native bsk_* tools, browser task previews, and screenshot results to the DeepSeek Harness Web UI. It uses the same bsk CLI and extension and includes its own BrowserSkill skill.

Upgrading to 0.3.3: update the CLI and extension before the plugin. The six browser_* tools have been renamed to bsk_*, without aliases for the old names. Update custom tool calls and policies, restart the DSH profile, and invoke /browser-skill again in existing conversations. See the migration guide.

With DeepSeek Harness, pnpm, and bsk installed and the extension connected, add the plugin to your profile:

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

Replace web with your profile name. Make sure bsk is available on the PATH used to start DSH, or set the plugin's bskPath. In a conversation, invoke /browser-skill and describe the task. A separate bsk install-skill step is not needed.

Plugin usage and configuration · npm package

Give your agent the browser evidence behind a bug. Start capture before reproducing an issue on a website you are authorized to debug, then inspect the result in the extension or through the agent.

• Follow an operation: see its requests, console output, form-field values, and immediate or delayed page changes. Capture includes supported manual actions as well as agent actions.
• Inspect a request: read retained headers, submitted data, response bodies, timing, and errors. Filter traffic or inspect a specific JSON field.
• Investigate performance: inspect page-load metrics, API timing summaries, and suspected duplicate requests. Missing or partial evidence is identified explicitly.
• Test and keep evidence: configure task-local request modification, blocking, mock responses, or same-origin replay; save a JSON record to review or share later.

Try a task such as:

Use browser-skill to investigate why saving the form on http://localhost:3000 fails. Start website debugging before reproducing it, inspect the request, response and console, then export the evidence and end the session.

From the extension, open Quick Actions → Website debugging for an existing task. The evidence page connects the operation timeline, requests, Console, page context, Performance, and API analysis. Its history remains accessible after the task ends, even without a daemon connection. A new agent task needs a user-provided export to inspect an ended task's history.

Request replay sends a new request using the page's current session and can change server data. Capture and redaction have limits; retained evidence may still contain sensitive information. See website debugging for the workflow, CLI examples, and limits.

Use Quick Actions → Full-page screenshot for automatic scrolling, a long image you scroll yourself, or the visible area. This extension feature also works without an agent or daemon connection.

For a page in an agent session:

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

Agent capture supports background tabs without focusing the window and restores the original scroll position when the document remains available. Full-page capture follows the document's scroll area; nested scrolling panels and virtualized lists have limitations. Screenshot guide

Open the extension in the intended profile and choose Copy profile instructions, then send those instructions with your task. You can also assign a unique Browser name and select it explicitly:

bsk browsers
bsk session start --browser "Work profile" --no-focus --json

The name is set in BrowserSkill; it is not automatically taken from Chrome's profile name. Each session stays bound to the selected instance. Profile selection guide

Keep the browser and its logins on your computer while the agent, CLI, and daemon run on a server. Pair the extension with that server over authenticated WSS; the browser initiates the connection, so your computer needs no inbound port.

The built-in server supports device pairing, renewal, and revocation. The bsk upload and bsk download file-transfer commands remain local-only. Authorized video exports can write to the CLI machine, including a remote server; Save MP4 as in the extension writes to the browser computer. Remote connection guide

An Agent Window shares the selected profile's login state; it is not a separate account or security sandbox. Agents can act with the permissions of the signed-in websites, so choose the tasks and agent you trust.

The extension has two independent Automation settings, both enabled by default:

These browser settings apply to existing and new sessions. Legacy --unattended, tab borrow --no-confirm, and BSK_REQUEST_HELP=off inputs cannot override them. Disabling human help does not mean the requested step was completed. Close the Agent Window to stop its tasks.

BrowserSkill does not operate a mandatory cloud service or collect product telemetry. Automation results go to your selected daemon or gateway and the agent using it; that agent or service may process or retain them under its own policies. The extension does not independently call an AI provider.

These features offer export and deletion. Stopping a task or disconnecting does not delete retained history or videos; expiration is applied during access or cleanup. Exported copies and copies already received by an agent or gateway must be managed separately. Known secrets are filtered from debugging evidence, but redaction cannot guarantee that all sensitive data is removed. Video frames are not automatically redacted; review visible content before sharing.

Privacy policy · Operation audit · Debugging retention and limits

Finish active browser tasks, then update the CLI:

bsk update --yes

For the default local setup, this installs the new executable and checks that it runs while the daemon keeps serving, then restarts the daemon from it on the same port. If the restarted daemon does not become ready, the previous executable is put back and the daemon is restarted from it. A daemon started with --foreground is left running on the previous version; restart it in its terminal or supervisor. So is a background daemon when bsk update runs where it could not start one again, such as inside a sandbox whose Windows Job forbids breakaway; restart it with bsk daemon restart outside the sandbox. If you use the installer to replace the binary, restart the daemon afterwards with bsk daemon restart.

A daemon that bsk started in the background also checks for a new release every 30 minutes and, while no agent session is active, installs it the same way. It then starts a daemon from the new executable and exits only once a daemon of the new version serves the same port. If the new daemon exits or is not ready within 20 seconds, it is stopped, and the running daemon puts the previous executable back, serves again on the same port, and retries that release after 6 hours. Browser connections drop for a moment during a handover and reconnect. A daemon that stops for another reason during an update, such as going idle, puts the previous executable back first. A daemon started with --foreground belongs to its terminal or supervisor, so it only reports new releases: run bsk update, then restart the daemon there. If bsk cannot write next to its executable, it only reports new releases; update it with the installer or package manager you used. Set BSK_AUTO_UPDATE=off to disable daemon-side auto-update while keeping manual bsk update available.

bsk doctor shows the last update attempt; update-state.json in the bsk home keeps its stage, result and error. Updates of one executable run one at a time, even from different bsk homes, through .bsk.update.lock (.bsk.exe.update.lock on Windows), which stays next to it. Until an update is confirmed, the previous executable stays next to the new one as .bsk.old-* (.bsk.exe.old-* on Windows); one that is still running remains until its process exits, and a later daemon start removes it. On Windows, self-update renames the running executable, which NTFS supports; where the file system refuses, the update fails and leaves the installation unchanged. bsk supports Windows 10 and Windows Server 2016 or later.

Update the extension through its browser store. Update the DSH plugin separately, then restart its profile:

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

Check bsk --version, bsk status, and bsk doctor. Keep the CLI, running daemon, extension, and optional DSH plugin on matching releases for new features. This README describes the current repository; store builds can lag during review. Check the changelog and releases for availability.

Managed CLI skills update on daemon startup, session start, or doctor while their files remain unchanged. Local edits and custom skills are preserved. Start a new agent session to load updated instructions; doctor reports any paused skill updates.

The repository is a Rust + pnpm workspace. For a source build, use Rust stable, Node.js 22, and the pnpm version declared in package.json:

pnpm install --frozen-lockfile
cargo build --release --locked
pnpm ext:build

The CLI is built under target/release/; load apps/extension/dist/chrome-mv3/ as an unpacked extension. For extension development, use pnpm ext:dev.

Run cargo test --workspace --locked, pnpm ext:test, and pnpm lint for the relevant checks. See the browser evaluation guide for reproducible browser cases. Bug reports and focused contributions are welcome through GitHub Issues and pull requests; remove sensitive data before attaching browser evidence.

The extension interface supports English, Simplified and Traditional Chinese, Korean, Japanese, French, Italian, Spanish, German, and Brazilian Portuguese. See localization to contribute translations.

MIT