Skip to content

README.en.md

Latest commit

 

History

History
223 lines (163 loc) · 9.04 KB

README.en.md

File metadata and controls

223 lines (163 loc) · 9.04 KB
Raw

DSH Browser Control

DSH Browser Control

简体中文 · English

release license Awesome DSH Plugin chrome mv3 dsh plugin cdp 11 browser tools tests

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

DSH Browser Control — a whale searching Google with a mouse

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:^"
  1. In cordis.patch.yml plugins list:
- id: browser-bridge
  name: '@deepseek-ai/dsh-browser-bridge'
  config:
    enabled: false
  1. 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).