# BrowserSkill
<p align="center">
<img src="docs/assets/browserskill-readme-banner.png" alt="BrowserSkill — connect your AI agent to your browser" />
</p>
<p align="center">
<strong>Let AI agents work in your logged-in browser while you keep working.</strong>
</p>
<p align="center">
English · <a href="README.zh-CN.md">中文</a>
</p>
<p align="center">
<a href="#quick-start">Quick start</a> ·
<a href="#website-debugging">Website debugging</a> ·
<a href="#deepseek-harness-plugin">DSH plugin</a> ·
<a href="#documentation">Documentation</a> ·
<a href="CHANGELOG.md">Changelog</a>
</p>
**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.
## What you can do
| Capability | What it gives you |
| --- | --- |
| **Work with your existing accounts** | Use the browser's current login state to read documents, search internal sites, fill forms, and complete web workflows. |
| **Keep browser tasks visible** | Give the agent its own window, borrow an existing tab when needed, and take over for login, verification, or other human-only steps. |
| **Read, interact, and capture** | Inspect page text and controls, click and type, manage tabs, capture viewport or full-page screenshots, and upload or download files in local mode. |
| **Debug websites with evidence** | Connect actions to requests, response bodies, console messages, and page changes. Inspect performance, slow APIs, and suspected duplicate requests; use explicit HTTP rules or request replay to test a hypothesis. |
| **Choose the right browser** | Name browser instances, bind a task to a specific profile, or pair an agent running on a server with a browser on your computer. |
| **Review what happened** | Reopen browser-local debugging history, export evidence as JSON, or enable a separate operation audit to review task activity. |
| **Extract structured data** | Export loaded tables and lists as JSON/CSV with column names, page/frame sources, merged-cell metadata and explicit coverage. See [structured extraction](docs/structured-extraction.md). |
| **Record a task as video** | Ask the agent to record one authorized tab as a silent MP4, then preview, save or delete the video from the extension. See [task video recording](docs/video-recording.md). |
| **Wait for page conditions** | Wait for a requested element condition with an explicit timeout before continuing a workflow. See [element waits](docs/wait-for-element.md). |
Watch a browser task in action:
https://github.com/user-attachments/assets/db782c92-b1d4-4aae-a255-039675937a90
## Quick Start
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.
| Component | Supported environments |
| --- | --- |
| CLI / daemon | macOS: Apple Silicon and Intel · Linux: x64 and ARM64 · Windows: x64 |
| Extension | Chrome and Microsoft Edge, based on Chromium 125 or later. Other Chromium browsers may work; compatibility is not guaranteed. |
| Agent integration | A shell-capable agent with the BrowserSkill skill, or DeepSeek Harness with the [DSH plugin](#deepseek-harness-plugin). |
### Let your agent set it up
Send this to your agent:
```text
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](https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi)** · **[Install for Edge](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg)**
<details>
<summary><b>Manual setup</b></summary>
#### 1. Install the CLI
macOS / Linux:
```sh
curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
```
Windows PowerShell:
```powershell
irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
```
By default, the binary is installed under `~/.local/bin`. Check it in the terminal or agent environment that will use it:
```sh
bsk --version
```
If an already-running agent cannot find `bsk`, restart it to pick up the new PATH, or configure the installed binary's absolute path.
#### 2. Connect the extension
Install it from the [Chrome Web Store](https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi) or [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg). Open its popup, enable the local connection, and check its status after starting the CLI.
#### 3. Install the skill for your agent
```sh
bsk install-skill
```
Select your harness with **Space**, then press **Enter**. For non-interactive setup, choose it explicitly:
```sh
bsk install-skill --harness cursor --json
```
Use `bsk install-skill --list` to see supported targets and paths. Existing installations are skipped unless you explicitly replace them with `--force`. For another harness, copy the entire [`crates/bsk-cli/skill/`](crates/bsk-cli/skill/) directory into its skills directory as `browser-skill/`, including `references/`.
DSH users should install the [plugin](#deepseek-harness-plugin) instead; it includes the skill.
#### 4. Check the connection
```sh
bsk doctor
```
Resolve any failed checks and confirm that the extension shows **Connected**. Start a new agent session and check that it can discover `browser-skill`; a successful doctor check alone does not confirm skill discovery.
</details>
### Try your first task
Once connected, ask your agent:
```text
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.
<details>
<summary><b>Try the CLI directly</b></summary>
Start a session and keep the returned `session_id`:
```sh
bsk session start --json
```
Replace `<id>` with that value in each command below. With multiple connected browsers, select one using `--browser <instance-id-or-name>` when starting the session. Background creation is the default; `--no-focus` remains supported, and `--focus` explicitly brings the new window forward. Requests for human help and interactive recording still bring the relevant window forward.
```sh
bsk navigate https://example.com --session <id>
bsk observe --session <id>
bsk screenshot --session <id> --out example.png
bsk session stop <id>
```
Use `bsk --help` or `bsk <command> --help` for command options. Always stop your session when finished, including after a failed task; borrowed tabs are returned to their original window.
</details>
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](docs/sandboxed-agents.md) for shared `BSK_HOME`, `BSK_AUTO_START=0`, and the independent-terminal fallback when the host cannot keep a task alive.
## DeepSeek Harness plugin
The [DSH plugin](packages/dsh-plugin-browserskill/README.md) 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](packages/dsh-plugin-browserskill/README.md#breaking-tool-api-migration-033).
With DeepSeek Harness, pnpm, and `bsk` installed and the extension connected, add the plugin to your profile:
```sh
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](packages/dsh-plugin-browserskill/README.md) · [npm package](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)
## Website debugging
**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:
```text
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](docs/website-debugging.md) for the workflow, CLI examples, and limits.
## More workflows
### Capture a full page
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:
```sh
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](docs/long-screenshot.md)
### Choose a browser profile
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:
```sh
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](docs/browser-profiles.md)
Add `--incognito` to isolate a task from the profile's ordinary website login state.
Enable the extension's **Allow in incognito** setting first. Incognito tasks cannot
borrow tabs, and all incognito windows in a profile share login state with each other.
[Incognito guide](docs/browser-profiles.md#incognito-agent-windows)
### Run the agent on a server
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](docs/remote-extension-connection.md)
## Browser control and privacy
By default, 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:
| Setting | What it controls |
| --- | --- |
| **Confirm before borrowing tabs** | Ask before an agent takes control of one of your existing tabs. Turning it off permits borrowing without that prompt. |
| **Allow requests for human help** | Let the agent ask you to handle login, verification, or another step that needs your participation. |
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.
| Optional history and recordings | Where it is saved | What to know |
| --- | --- | --- |
| **Website debugging** | The current browser profile, including in remote mode | Retains captured evidence, including available bodies and field values. Stopped records expire after 30 days, with a 50-record / 50 MiB retention budget and earlier eviction when necessary. Stop capture before deleting a record. |
| **Operation audit** | The daemon's host, under `BSK_HOME/audit` | Off by default. Records task and operation metadata, excluding input values, page bodies, screenshots, and file contents. Ended tasks expire after 30 days. |
| **Task video** | The current browser profile; exported copies at the chosen destination | Opt-in, silent capture of one authorized tab, limited to 10 minutes / 256 MiB per video. Recordings expire 24 hours after creation; the temporary video budget is 1 GiB. The library supports preview, export and deletion. |
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](apps/extension/PRIVACY.md) · [Operation audit](docs/operation-audit.md) · [Debugging retention and limits](docs/website-debugging.md#history-and-export)
## Updating
Finish active browser tasks, then update the CLI:
```sh
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:
```sh
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](CHANGELOG.md) and [releases](https://github.com/Tencent/BrowserSkill/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.
<details>
<summary><b>Custom ports, sandbox hosts, and remote servers</b></summary>
Stop the daemon in its owning host or supervisor, update with `bsk update --yes --no-restart-daemon`, then start it there with its original flags and `BSK_HOME`. Use `BSK_AUTO_START=0` in agent commands during this process. Follow the [sandbox](docs/sandboxed-agents.md) or [remote](docs/remote-extension-connection.md) guide for your deployment.
</details>
## Documentation
| Goal | Guide |
| --- | --- |
| Install and verify with an agent | [Agent setup](AGENT_INSTALL.md) |
| Investigate a website or API | [Website debugging](docs/website-debugging.md) |
| Capture long pages | [Full-page screenshots](docs/long-screenshot.md) |
| Record and save a task video | [Task video recording](docs/video-recording.md) |
| Export tables or lists | [Structured extraction](docs/structured-extraction.md) |
| Wait for an element condition | [Element waits](docs/wait-for-element.md) |
| Use a specific account or profile | [Browser profiles](docs/browser-profiles.md) |
| Connect a server-side agent | [Remote browser connections](docs/remote-extension-connection.md) |
| Run in a sandbox | [Sandboxed agents](docs/sandboxed-agents.md) |
| Review recorded task metadata | [Operation audit](docs/operation-audit.md) |
| Integrate with DeepSeek Harness | [DSH plugin](packages/dsh-plugin-browserskill/README.md) |
| Understand the implementation | [Architecture](docs/architecture.md) · [Protocol](crates/bsk-protocol/README.md) |
## For Developers
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`:
```sh
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`.
| Directory | Component |
| --- | --- |
| `crates/bsk-cli` | CLI, daemon, and bundled agent skill |
| `crates/bsk-protocol` | Wire types and JSON schemas |
| `apps/extension` | Browser automation, debugging workspace, and extension UI |
| `packages/dsh-plugin-browserskill` | DeepSeek Harness integration |
| `packages/ui`, `packages/i18n`, `packages/vom` | Shared UI, localization, and page observation |
| `evals/browser` | Local test pages and browser capability evaluations |
Run `cargo test --workspace --locked`, `pnpm ext:test`, and `pnpm lint` for the relevant checks. See the [browser evaluation guide](evals/browser/README.md) for reproducible browser cases. Bug reports and focused contributions are welcome through [GitHub Issues](https://github.com/Tencent/BrowserSkill/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](packages/i18n/README.md) to contribute translations.
## License
[MIT](LICENSE)