BrowserSkill/packages/dsh-plugin-browserskill

One-Sentence Pitch

Wraps BrowserSkill's browser automation capabilities (CLI called bsk) as native model tools for DeepSeek Harness, allowing AI to complete tasks in your existing browser without interrupting your normal browsing.

Core Capabilities

• Registers 11 browser_* model tools within the DSH process: session start/stop/list, navigation, snapshots, semantic observation, click, fill, keypress, screenshot, device emulation — each tool corresponds to one bsk <cmd> --json call
• Drives multiple browser sessions simultaneously: each browser_session_start returns an independent session ID, supporting up to 5 concurrent sessions; when no session parameter is passed, it falls back to the most recently operated session
• Strict ownership boundaries: the plugin only tracks sessions it starts; external session IDs are directly rejected; the list tool only shows sessions it owns; on unload, it only cleans up its own sessions, never affecting sessions from other programs shared in the bsk daemon
• Serial command execution per session: the bsk daemon accepts only one incomplete command at a time; the plugin uses per-session FIFO to queue model tool calls and observation traffic into the same channel
• Progressive disclosure: when lazyTools=true (default), the schemas for all 11 tools won't appear in the system prompt; only after the model actually calls browser-skill (or user inputs /browser-skill) will the full tool set reveal itself for the remainder of the current process lifecycle
• Cancellation semantics connected: DSH's cancellation signal propagates to the runner, SIGTERM kills the running bsk subprocess (SIGKILL after 2 seconds if it doesn't exit), and the model can continue to the next step
• DSH Web UI floating window observation: each owned session has a real-time thumbnail, current action, and timer; it can be dragged/scaled, can interrupt the current command with one click, and can be upgraded to a native picture-in-picture window; the frontend fetches data via loopback routes provided by the host webServer
• Lightweight probe at startup: immediately runs bsk --version after plugin loads; if missing, issues a warning early; on first tool call, returns installation guidance instead of a raw spawn error

Technical Implementation

• Language: TypeScript
• Key Dependencies: @deepseek-ai/cordis (^4.0.1, plugin injection and config validation), @deepseek-ai/dsh-tools + @deepseek-ai/dsh-llm (^0.1.0-rc.6, tool registration and content block types), @deepseek-ai/schemastery (^3.18.1, Config Schema), node:child_process (spawn bsk subprocess)
• Architecture Pattern: Dual-sided Cordis plugin (dsh.bundle.patch injects the tools service; dsh.client injects web frontend React tool view), validates config through Schemastery Config; establishes session registry + per-session FIFO executor + observation service trio at startup, then uses ctx.inject(["webServer"], ...) to defer mount HTTP routes; the model's visible tool set follows "progressive disclosure" — before skill call, only directory entries are mounted, not the 11 tool schemas
• Entry Files: src/index.ts (plugin apply entry + Config Schema), src/tools.ts (11 model tool definitions), src/runner.ts (bsk subprocess spawn + cancellation/timeout/error envelope parsing), src/sessions.ts (session ownership registry), src/lazy-tools.ts (skill call tool set revelation listener), src/observation.ts + src/observation-http.ts (observation service and loopback HTTP routes)

Use Cases

When you want AI to complete tasks in your real browser that require login state or visual interface (such as scraping content that needs login, cross-page form filling, simulating mobile behavior, or operating on your own existing tabs), and you don't want to create a separate test browser account for it — this plugin is the bridge. It borrows the window isolated by the browser extension; your regular tabs remain unaffected. The window is returned after AI completes the action or when you press interrupt.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:Tencent/BrowserSkill/packages/dsh-plugin-browserskill

Configuration Options

FAQ

Q: Can this plugin run without installing bsk CLI and browser extension?

A: It can load, but all browser_* tool calls will fail. The plugin only logs a warning at load time; on first tool call, the runner catches the spawn error and returns a human-readable message with installation links instead of a raw ENOENT.

Q: After a session ends, does the Agent Window in the browser extension close automatically?

A: Yes. browser_session_stop calls bsk session stop <id>, and the browser extension reclaims the corresponding Agent Window; when the plugin unloads, it closes all still-living sessions in the owned list and releases bsk subprocesses.

Q: Where does the plugin store browser sessions? Do they persist across restarts?

A: Only in memory. SessionRegistry is an in-process Map; unloading the plugin loses it; next startup requires going through browser_session_start again. lazyTools scans persisted event logs during session recovery; if it finds successful browser-skill calls in history, it auto-reveals the tool set, but closed sessions won't be revived.

Q: Can the observation floating window's screenshots be accessed from external networks?

A: No. These routes only accept loopback requests (localhost / 127.0.0.0/8 / [::1]), and replicate the browser trust barrier DSH adds to its own /api routes: Origin and Host must match, sec-fetch-site: cross-site is always rejected, POST must be application/json. If you bind DSH webServer to 0.0.0.0 and access via LAN, the barrier will actively fail — this is by design, not a bug.

Q: Can I bypass the plugin and call bsk directly via bash?

A: Don't. The skill's prelude explicitly states: browser tasks in DSH must go through injected browser_* tools; bypassing the plugin to call bsk directly loses session ownership, observation floating window, tool cards, and unload cleanup; from the model's perspective, such "bypassed" calls are considered erroneous behavior.

Q: Is the "Interrupt" button in the floating window the same as the Stop button in chat?

A: Behaviorally equivalent — both send SIGTERM to the currently running bsk subprocess, interrupting that command; the agent main loop won't stop because of one interrupted command and will continue according to its set logic.

Learning Curve

Advanced — requires installing bsk CLI and browser extension as two local dependencies first, and understanding the plugin only tracks "self-started" sessions as the boundary rule, but configuration options are few and all optional, working out of the box.

Known Issues & Limitations

• Long-running commands (like bsk record) currently do not go through the background job channel via ctx.jobs; they still block as synchronous tool calls until completion, which is listed in README as future work
• bsk console and bsk network CLI verbs currently don't have corresponding browser_* tools; the skill prelude explicitly notes this
• The Web UI's picture-in-picture (Document PiP) button depends on browser native capabilities; Chrome/Edge support it but require a one-time user gesture; browsers that don't support Document PiP will directly hide that button instead of falling back
• Observation floating window HTTP routes require the host to bind to loopback addresses; trying to access DSH webServer bound to 0.0.0.0 via LAN will be actively rejected by the browser trust barrier — this is expected behavior; for cross-network access, you must add an authentication layer in front
• Tool calls must first obtain their own session ID via browser_session_start before they can be used; other tools will directly error when "there's no session yet"; browser_session_list won't show sessions created by other programs sharing the bsk daemon (this is by design, not a bug)

Let AI agents use your browser without interrupting your work.

English · 中文

BrowserSkill connects Cursor, Claude Code, Codex, OpenClaw, CodeBuddy, WorkBuddy, Pi, Hermes Agent, DeepSeek Harness, and other AI agents to your already logged-in browser.

Need the agent to touch a tab you already have open? It must borrow that tab explicitly, return it when the task is done, and leave the rest of your browser alone.

https://github.com/user-attachments/assets/db782c92-b1d4-4aae-a255-039675937a90

BrowserSkill Advantages

• Reuse real login state: Agents can work with sites you are already signed into, without separate test accounts.
• Keep working uninterrupted: browser tasks run in a separate, visible Agent Window, so you can keep using your own browser.
• Support any Agent: any Agent that can call a shell can use BrowserSkill through the bsk CLI, with no lock-in to a specific model, Agent framework, or harness.
• Built-in human-in-loop: when a task hits captcha, login, confirmation dialogs, or other human-only steps, the Agent can ask you to take over and then continue afterwards.

Runtime Environment

BrowserSkill has two local runtime pieces: the bsk CLI/daemon and the browser extension.

Quick Start

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

Manual install

Install the CLI, then install the extension from the Chrome Web Store or Edge Add-ons.

1. Install the bsk CLI

macOS / Linux (recommended — installs to ~/.local/bin):

curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh

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

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

Verify the binary:

bsk --version

2. Install the browser extension

Install BrowserSkill from your browser's store:

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

On other Chromium-based browsers, install the Chrome Web Store build.

3. Install the skill

BrowserSkill ships a skill that teaches your agent harness how to use bsk. For these harnesses, install it in one step:

Cursor

Claude Code

Codex

OpenClaw

CodeBuddy

WorkBuddy

Pi

Hermes Agent

bsk install-skill

Use Space to select the Agent harness you want to install into, then press Enter to install the skill. Run bsk install-skill --list to see internal variants and install paths.

Other shell-capable agent harnesses are supported too. Copy skill/SKILL.md into your harness's skills directory as browser-skill/SKILL.md to install the skill manually. DeepSeek Harness uses a dedicated plugin instead — see DeepSeek Harness plugin.

Start a new Agent session and write a prompt that needs the browser, for example:

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

DeepSeek Harness plugin

Using DeepSeek Harness (dsh)? BrowserSkill ships a first-class dsh plugin on npm as @wxg-prc-cpg/browser-skill-dsh-plugin. It injects native browser_* tools (no shelling out to bsk) and a live Web UI overlay of each Agent Window.

Add it to a dsh profile, then start that profile:

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

The plugin carries its own copy of the skill, so bsk install-skill is not needed for dsh — but the bsk CLI and the browser extension are still prerequisites. See the plugin README for the tool list, configuration, and the observation overlay.

How It Works

BrowserSkill is a local bridge between your agent harness and your browser.

flowchart TB
  subgraph Harness["Agent Harness"]
    Agent["Cursor / Claude Code / Codex / OpenClaw"]
  end

  subgraph Local["Your Machine"]
    CLI["bsk CLI"]
    Daemon["bsk daemon"]
    Extension["BrowserSkill extension"]
  end

  subgraph Browser["Browser Profile"]
    AgentWindow["Agent Window"]
    UserWindows["Your normal browser windows"]
  end

  Agent -->|"shell: bsk ..."| CLI
  CLI -->|"local IPC"| Daemon
  Daemon -->|"WebSocket on 127.0.0.1"| Extension
  Extension -->|"automates"| AgentWindow
  Extension -.->|"borrow tab only when asked"| UserWindows

  style AgentWindow fill:#fff4e6,stroke:#f59e0b,stroke-width:2px,color:#111827
  style UserWindows fill:#f8fafc,stroke:#cbd5e1,color:#334155

The agent never talks to the browser directly. It asks the bsk CLI to perform a browser task; the local daemon routes that request to the extension; the extension runs it in an Agent Window. DeepSeek Harness takes the same path through the plugin: the agent calls injected browser_* tools, and the plugin invokes bsk on its behalf.

For Developers

The repository is a Cargo + pnpm workspace:

• crates/bsk-cli — bsk CLI and local daemon
• crates/bsk-protocol — shared wire types and JSON schemas
• apps/extension — browser extension
• packages/ui and packages/i18n — shared extension UI support
• packages/dsh-plugin-browserskill — DeepSeek Harness plugin (@wxg-prc-cpg/browser-skill-dsh-plugin)

License

MIT