Dsh Browser AI Agent

dsh Browser Control

English | 中文

<img width="1701" height="897" alt="dsh Browser Control" src="https://github.com/user-attachments/assets/3b1f3a25-f962-4e02-a9ef-d23e0d01fc8e" />

Connect DeepSeek Harness to the Chrome or Firefox tabs you are already using. The model can read page content, operate controls, navigate, and manage tabs while preserving your login state, session, and cookies. A side panel or sidebar provides the conversation UI.

dsh is DeepSeek AI's open-source, plugin-based agent harness. This repository provides a companion browser bridge plugin and Chrome/Firefox MV3 extension as one standalone pnpm workspace.

Pages become structured text with a numbered inventory of interactive elements. Tools address elements by number or selector; browser_screenshot captures the controlled tab's viewport after approval. The side panel also accepts PNG, JPEG, WebP, and GIF attachments when the host advertises image support.

[!IMPORTANT] The workspace is pinned to DSH 0.2.2-rc.2.

Quick install

The installer installs the bridge plugin and Chrome extension.

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash

Windows, in PowerShell:

$s="$env:TEMP\dsh-install.ps1"; irm https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.ps1 -OutFile $s; powershell -NoProfile -ExecutionPolicy Bypass -File $s

When the installer opens chrome://extensions, follow its instructions to load or reload dsh Browser Assistant. If dsh is already running, restart it after installation. See Detailed installation and usage for prerequisites, startup commands, updates, and developer installation.

[!IMPORTANT] The unscoped dsh-browser package on npm belongs to a different project and is not affiliated with this repository. This project is not currently published as an npm package; use the installer above.

Performance

In a paired 60-run end-to-end benchmark on August 18, 2026, both backends completed all 30 assigned runs successfully, while dsh Browser Control required fewer model/tool round trips and finished faster:

Backend	Success	Mean end-to-end latency	Mean browser tool calls
dsh Browser Control	30/30	5.32 s	3.4
Matched Playwright baseline	30/30	6.67 s	4.7

The paired Playwright / extension duration ratio was 1.24 (95% CI 1.16–1.34): Playwright took about 24% longer, or equivalently, dsh Browser Control reduced latency by about 20% and saved 1.35 seconds per task on average. The suite used six browser tasks, five deterministic seeds, the same DSH profile and model (deepseek-v4-flash), and independently validated page state. See the benchmark methodology and reproduction guide.

Core capabilities

Capability	Tool	Notes
Read page	browser_snapshot	Structured text snapshot: title, URL, main text, numbered controls, and masked form fields; delta: true returns only changes, frame reads one iframe, and query locates any element by text/selector/role and returns its selector
Click	browser_click	Click or double-click by index or selector; supports mouse buttons and modifiers
Text	browser_type	React/Vue-compatible input; replace clears the field first, and mode selects caret insertion or per-character key events
Press keys	browser_press	Single keys or chords (modifiers); action: down/up holds a key across calls and repeat repeats it
Scroll	browser_scroll	Scroll the page or selected iframe up, down, to the top, or to the bottom
Clipboard	browser_clipboard	write puts text/HTML on the system clipboard; paste delivers it as a paste event or a real platform shortcut
Files	browser_upload	Attach local files to an input[type=file] (Chrome)
Navigate	browser_navigate / browser_open_tab / browser_back / browser_forward / browser_reload	Navigation inside the controlled tab, or open a URL in a new tab and follow it (active:false keeps the current tab in front)
List tabs	browser_list_tabs	List accessible tabs with stable IDs, titles, URLs, window/index metadata, and active/controlled state
Follow tab	browser_follow_tab	Bind later browser tools to a tab returned by browser_list_tabs; it stays in the background unless activate: true
Close tab	browser_close_tab	Close a tab returned by browser_list_tabs
Read region	browser_get_text	Lazy-loaded or partial page text
Wait for stability	browser_wait	Page-load and render-settle detection
Send images	session.prompt / session.attachment	Host-capability-gated image drafts, image-only prompts, and durable history previews
Quote a selection	side panel composer	Text you highlight in the page appears in the composer and is sent with your next message as fenced, attributed page content
Continue generating	side panel	Continue an interrupted response when the host offers it

Clicks, text entry, and scrolling run in the selected document, including cross-origin iframes. Chrome uses its debugger for native keyboard events, caret insertion, system paste, and file uploads. Screenshots require an active tab in a focused window; browser_follow_tab { activate: true } brings the controlled page to the front.

Detailed installation and usage

Requirements: Node.js >=24.9.0, Corepack/pnpm, and Chrome 125+ or Firefox 140+. Windows additionally needs Windows PowerShell 5.1, which ships with Windows, or PowerShell 7+.

Install or update

Run the quick install command to install or update. The installer opens chrome://extensions; load ~/.dsh/browser-extension as an unpacked extension the first time, or click Reload after an update. Restart dsh if it is already running.

To install the current branch from a source checkout instead:

git clone https://github.com/Lum1104/dsh-browser.git
cd dsh-browser
./scripts/install.sh

On Windows, run .\scripts\install.ps1 from the checkout instead. After pulling or switching revisions, rerun the installer and reload the extension.

Uninstall

Open Settings → Uninstall dsh-browser in the extension, copy the command, and run it in Terminal.

You can also run it directly. On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/uninstall.sh | bash

On Windows:

& { $ErrorActionPreference = 'Stop'; $d=New-Item -ItemType Directory -Path (Join-Path ([IO.Path]::GetTempPath()) ('dsh-browser-uninstall.'+[Guid]::NewGuid().ToString('N'))); try { $s=Join-Path $d.FullName 'uninstall.ps1'; Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/uninstall.ps1 -OutFile $s; powershell -NoProfile -ExecutionPolicy Bypass -File $s } finally { Remove-Item -LiteralPath $d.FullName -Recurse -Force } }

From a checkout, run bash scripts/uninstall.sh or .\scripts\uninstall.ps1.

Firefox source build

Firefox uses a separate MV3 manifest, event-page background, and sidebar. Build it from a checkout, then open about:debugging#/runtime/this-firefox, choose Load Temporary Add-on, and select extensions/dsh-browser/dist-firefox/manifest.json:

pnpm install
pnpm --filter dsh-browser-extension run build:firefox

The bridge address is still auto-discovered. Firefox's moz-extension:// UUID does not authenticate an add-on, so copy the bearer token from ~/.dsh/ext-bridge-token into the extension settings (the dsh startup log reports that file's path). Signed distribution can package the same dist-firefox/ output.

Start and use

Start the managed installation with:

cd ~/.dsh/dsh-browser && pnpm start

From a source checkout, run pnpm start in the repository root. The exact supported public runtime is:

npx @deepseek-ai/dsh@0.2.2-rc.2 web

Local Chrome use requires no configuration; Firefox requires the local bridge token described above. Open a page, click the DeepSeek whale icon, and wait for Connected. Existing HTTP(S) tabs are instrumented on the first action. On browser-protected pages and extension stores, the model can read tab metadata and use browser-level HTTP(S) navigation, back, forward, and reload, but it cannot inspect or operate the protected page DOM.

Troubleshooting

Side panel stays "Not connected"

• Make sure DSH is running. After installing or updating, restart DSH and reopen the side panel.
• Open Settings → Detect and select your DSH instance.
• In Firefox, enter the token from ~/.dsh/ext-bridge-token in Settings.
• For a remote DSH instance, enter its server address and bridge token in Settings.

Development

The bridge plugin and Chrome/Firefox extension are both members of this repository's workspace. Run all commands from the repository root. For the first development installation, run pnpm install.

Package documentation: browser bridge and browser extension.

pnpm run build
pnpm run typecheck
pnpm run test
pnpm run check:runtime
pnpm run test:smoke

pnpm --filter @yuxianglin/dsh-bridge-browser run build
pnpm --filter @yuxianglin/dsh-bridge-browser run typecheck
pnpm --filter @yuxianglin/dsh-bridge-browser run test

pnpm --filter dsh-browser-extension run build
pnpm --filter dsh-browser-extension run build:firefox
pnpm --filter dsh-browser-extension run test

Notes:

• The bridge plugin must have a built lib/ before startup because the loader consumes it; both scripts/install.sh and the root pnpm run build build the plugin before the extension.
• The dependencies of @deepseek-ai/dsh and the bridge plugin are pinned to the same tested public release line. An upgrade must update the manifests and lockfile together and rerun the root checks.

check:runtime checks the resolved DSH dependencies and lockfile; test:smoke starts the real web host in a temporary DSH home and verifies the bridge and session reads after a restart, without model credentials. CI runs these checks after a clean installation.

After building, run pnpm test:browser with a Playwright Chromium installation, or set CHROMIUM_PATH to a Chromium executable that supports loading unpacked extensions. This starts real DSH and Chromium instances to verify sharing controls, developer-tools consent, input, iframe uploads and targeting, and CSS edits. Site isolation is enabled and verified for cross-site frames; element clicks, input, and scrolling cover same-origin, cross-origin, and nested frames. It needs no model credentials and saves results under .artifacts/browser-smoke/.

After building the extension, run pnpm test:uninstall. Run pnpm test:uninstall:ui for the settings UI tests; Playwright Chromium is required.

Security

• Page text read by the assistant and attachments you send are passed to the selected model.
• Page content sharing offers Share automatically (default), Ask every time, and Off.
• Text snapshots mask password and payment-card values. Screenshots capture visible pixels without masking.
• Page operations require approval by default. You can trust individual sites or enable Allow unrestricted browser control. Developer tools require separate authorization.
• When you switch tabs, the assistant asks which page to continue working on.