DSH Browser Control

简体中文 · English

A Chrome extension + DeepSeek Harness plugin that lets AI agents drive your real browser like a human.

What is this

Not a headless browser, not Puppeteer — your real Chrome, with your logins and cookies. The AI drives tabs through the Chrome DevTools Protocol while you watch every step on screen.

You say one sentence to the AI
      ↓
Agent calls browser_* tools
      ↓
DSH plugin (WebSocket bridge)
      ↓
Chrome extension (CDP)
      ↓
Your real browser performs the action
      ↓
Result returns to the Agent

How it differs from MCP browser solutions

Browsers via MCP (Playwright MCP, Puppeteer MCP, browser-use…) share one trait: they launch a fresh browser instance they downloaded themselves. This project takes the other road:

	This project	Playwright / Puppeteer MCP
Browser	The real Chrome you are using	Separate auto-downloaded instance
Logins / Cookies	✅ Fully inherited, no re-login	❌ Fresh profile every time
CAPTCHAs / QR login	Rarely hit — your sessions stay logged in	Frequently stuck at login walls
Visibility	Live on your screen, grab the mouse anytime	Headless or separate window
Environment deps	No Node / npx / Python needed	Needs npx or uvx runtime
Setup	Load extension + settings toggle	Edit MCP client JSON config
Disk usage	Reuses existing Chrome, zero extra	Downloads hundreds of MB
Integration depth	Native dsh plugin (settings card / status page / cleanup button)	Generic MCP server

In one line: for "use MY browser" tasks (logged-in Bilibili, Zhihu, admin panels), use this project; for generic cross-browser test automation, use MCP.

Download

File	Purpose
DSH-Browser-Control-1.0.7.zip	Chrome extension (unzip and load)
dsh-browser-control-plugin-v1.0.7.zip	dsh plugin (offline fallback; online installs use Option A/B)

Install the Chrome extension (30 seconds)

Download the zip → unzip to a fixed folder (don't delete it) → open chrome://extensions → enable Developer mode → click "Load unpacked" → pick the unzipped folder.

Whale icon in the toolbar = success. Requires Chrome 116+.

Install the dsh plugin

📦 This package is a bundle (package.json points dsh.bundle.patch at cordis.patch.yml). A successful dsh plugin add registers it under the profile's dsh.profile.bundles; a restart loads it.

Prerequisite: dsh plugin forwards to pnpm, so pnpm must be on PATH; the target profile is initialized automatically on first use.

Option A: install from npm (recommended)

# Install from the npm registry and register it with the profile
dsh plugin --profile web add @caob23/dsh-browser-control

If you manage the profile's node_modules yourself, plain npm works there too:

npm install @caob23/dsh-browser-control

Option B: install from GitHub or a local directory

# Straight from GitHub
dsh plugin --profile web add "github:caob23/dsh-browser-control#v1.0.7"

# Local checkout for debugging (note: the explicit file: prefix is required)
dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"

Restart DSH to load it. Uninstall:

dsh plugin --profile web remove @caob23/dsh-browser-control

⚠️ Always use the file: prefix for local directories. Bare / relative paths are treated as the link: protocol by pnpm, which does not materialize into node_modules top-level under hoisted layouts and fails to resolve at boot.

After installing and restarting, the bridge is on by default (v1.0.6+); no manual enable step. The status page at http://127.0.0.1:9777/ confirms the listener is up.

To opt out: set enabled: false under browser-bridge.config in ~/.dsh/settings.yml.

Option C: copy into the harness tree (legacy, v1.0.2 and earlier)

git clone https://github.com/caob23/dsh-browser-control.git
cd dsh-browser-control
git checkout v1.0.2   # legacy layout lives at the v1.0.2 tag
./install.sh /path/to/deepseek-harness

The script only copies plugin files into place — you still need the three manual config edits, then restart dsh:

Download dsh-browser-bridge-plugin-v1.0.2.zip and unzip into deepseek-harness/packages/web/browser-bridge/.

Then add three pieces of config:

1. In packages/bundle/base/package.json dependencies:

"@deepseek-ai/dsh-browser-bridge": "workspace:^"

2. In cordis.patch.yml plugins list:

- id: browser-bridge
  name: '@deepseek-ai/dsh-browser-bridge'
  config:
    enabled: false

3. In tsconfig.host.json references:

{ "path": "./packages/web/browser-bridge" }

Restart dsh → the "DSH Browser Control" card appears in Settings → enable it. Details in dsh-config/README.md.

Usage

1. dsh Settings → Plugins → DSH Browser Control → enable
2. The extension connects automatically (port 9777, default token dsh-local)
3. Talk in natural language; the agent drives the browser

Visit http://127.0.0.1:9777/ for connection status.

Tools

Tool	Purpose
browser_navigate	Navigate to a URL
browser_read	Read page text/HTML
browser_snapshot	Page snapshot → ref interaction tree
browser_click	Click an element (by ref / selector)
browser_type	Type into inputs
browser_press	Send keyboard keys
browser_scroll	Scroll the page
browser_tabs	Tab management (list/open/close/activate)
browser_evaluate	Run arbitrary JS
browser_screenshot	Capture page screenshot
browser_console_log	Captured page console entries (v1.0.7+)
browser_network_log	Captured HTTP request/response log (v1.0.7+)
browser_pdf	Export the current page as PDF (v1.0.7+)
browser_emulate	Switch to a device viewport (mobile / desktop / custom, v1.0.7+)
browser_cleanup	Clean up temp files

Architecture

Chrome browser
  └─ DSH Browser Control extension (MV3)
       └─ chrome.debugger (CDP)
            └─ WebSocket ──────→ DSH plugin (browser-bridge)
                                      └─ browser_* tools → Agent

Key design:

• Extension dials out to the bridge (no native messaging host)
• Off by default; enabled manually from Settings
• Persistent debugger attachment — banner stays visible during control
• Listens on 127.0.0.1 only, token-authenticated

Verified

Scenario	Result
Baidu search → extract result titles	✅
Bilibili user search → send DM	✅
Bilibili search → count video cards + screenshot	✅
Unit tests 29/29	✅
Type checks (host + client)	✅

Changelog

See CHANGELOG.md.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

• Personal / academic / non-commercial use: completely free — use, modify, and distribute freely under AGPL-3.0 terms
• Enterprise / commercial use: AGPL-3.0 treats networked use as distribution, requiring derivative code to be published. If you want to embed this project in closed-source products or build a SaaS on it without open-sourcing, contact the author for a commercial license (terms negotiated separately)
• Commercial licensing inquiries: GitHub Issues or email caob2333@outlook.com

See the LICENSE file for the full license text (AGPL-3.0).