Use DeepSeek Harness to read and interact with web pages directly through a Chrome extension. Capture plain text snapshots, click elements, fill forms, scroll, and navigate—all while preserving your login session.
- Language
- TypeScript
- License
- MIT
- Branch
- main
Install
$ dsh plugin --profile web add github:Lum1104/dsh-browserRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
Install via your agent
Install the DeepSeek Harness plugin Lum1104/dsh-browser for me: review the repository at https://github.com/Lum1104/dsh-browser first, then run the install command and verify the plugin loads successfully.
Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.
One-Line Description
dsh-browser connects DeepSeek Harness to your active Chrome tab: the model reads the page in plain text, clicks controls, fills forms, scrolls and navigates, while preserving login state and cookies; the sidebar provides a conversation interface, and operations require your confirmation step by step.
Core Features
- Read Page: Renders the current tab as structured text (including title, URL, numbered interaction list, form fields), with sensitive values displayed as
•••• - Click Elements: Click links, buttons, checkboxes and other controls by number, compatible with React/Vue controlled components
- Fill Forms: Input text into form fields by number, supports
replace=trueto clear first then fill - Send Keystrokes: Synthesize keyboard events like Enter, Tab, Escape, Arrow keys, Backspace, Delete, etc.
- Scroll and Navigation: Scroll up/down or jump to top/bottom; open new URLs within the tab, go back, go forward, refresh
- Wait for Stability: Detect page load and DOM rendering completion, with optional additional wait time
- Partial Reading: Read local text by CSS selector, useful for lazy-loaded or partial area content
Technical Implementation
- Language: TypeScript (both server and extension use TS, extension side includes React)
- Key Dependencies:
ws(WebSocket bridge transport),@deepseek-ai/dsh-host-apiproxy(DSH gateway RPC reuse),@deepseek-ai/schemastery(Config schema),react+marked+dompurify(sidebar UI) - Architecture Pattern: Cordis plugin
bridge-browser, mounts/ext/bridgeWebSocket upgrade route on the host webserver (located outside/apitrust fence, with bearer token authentication); same-named Chrome MV3 extension as client, bridges panel messages to WebSocket viachrome.runtime.connect; extension content script executesbrowser_*tools in the controlled tab - Entry Files:
packages/browser/bridge-browser/src/index.ts(bridge plugin),extensions/dsh-browser/src/background/index.ts(extension background),extensions/dsh-browser/src/panel/main.tsx(sidebar entry)
Use Cases
Suitable for users who want to integrate DeepSeek model into a "real browser" instead of a headless copy: when the target site is sensitive to login state, cookies, device fingerprints (like admin panels, e-commerce backends, social platforms), or when you need to preserve the current multiple tabs open by the user, the model can continue operating directly in the existing page. DSH's web profile thus gains an additional set of browser tools.
Prerequisites and Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.6 | Bridge plugin locks @deepseek-ai/dsh-* 0.1.0-rc.6 via peerDependencies; can only be installed on dsh web |
| Node.js | ^22.19 or >=24 | Root package.json doesn't declare engines, README specifies this range; installer validates node command exists |
| Package Manager | Corepack + pnpm | Installation script and build script (scripts/install.sh, root pnpm run build) both depend on pnpm |
| Chrome | >= 116 | Extension minimum_chrome_version: 116 in manifest.json (MV3 + sidebar API requirement) |
| Platform | Cross-platform | Bridge plugin only depends on Node and ws, no native modules; extension is Chrome MV3, theoretically cross-platform; install script's pbcopy and open work best on macOS |
| Native Modules | None | Bridge plugin doesn't introduce native modules; workspace only allows (doesn't force) build scripts from upstream dependencies like node-pty / koffi / esbuild |
Installation
dsh plugin --profile web add github:Lum1104/dsh-browser
Configuration
This plugin declares 6 adjustable fields via cordis.patch.yml (located in packages/browser/bridge-browser/cordis.patch.yml). Except for token, all have default values, so regular users don't need to modify them.
| Config | Type | Description | Default |
|---|---|---|---|
token | string | Bearer token for bridge connection; when missing, auto-generated and written to ~/.dsh/ext-bridge-token (permissions 0600). No token needed for local loopback connections, only needed for remote deployment | Auto-generated |
toolTimeoutMs | integer (ms) | Timeout for single browser tool call, after which the bridge will revoke the instruction sent to the extension | 90000 |
snapshotMaxChars | integer (chars) | Maximum characters for a single page snapshot render; content beyond this is truncated; minimum 500 | 32000 |
maxInteractiveItems | integer | Maximum number of numbered interactive elements in a single snapshot; elements exceeding this are discarded | 60 |
sessionWorkspacePath | path string | Default workspace directory for sessions created by the browser extension; empty string means no grouping | ~/.dsh/browser-sessions |
deferSessionCreate | boolean | Whether to defer session creation (return temporary ID first, persist to storage on user's first message) | true |
Two additional environment variables are supported: DSH_EXT_TOKEN (overrides token field, for fixed remote deployment token) and DSH_BROWSER_SESSION_WORKSPACE (overrides sessionWorkspacePath).
FAQ
Q: dsh is running after installation, but the sidebar shows "Not Connected" - what should I do?
A: The installer only registers the bridge bundle with the local web profile when dsh starts; already running processes don't automatically load new plugins. Stop that dsh process and re-run pnpm start (or npx @deepseek-ai/dsh web), the extension will automatically reconnect without needing reconfiguration.
Q: Do I need to copy-paste the Token?
A: Local loopback (127.0.0.1) connections don't require a token; the extension auto-detects and connects via /ext/bridge-config; only remote deployment with --host 0.0.0.0 requires filling in address and token in the sidebar settings. Tokens don't auto-rotate.
Q: Which pages cannot be read or operated on?
A: Built-in or protected browser pages (like chrome:// pages, Chrome Web Store) cannot have content scripts injected, so they don't support reading or operating; only normal http:// and https:// pages are supported. Pages already open before installation don't need manual refresh; the extension will auto-inject on first operation.
Q: Will passwords or bank card numbers be sent to the model?
A: No. Sensitive fields (type=password and payment card numbers) are always displayed as •••• in snapshots, field values don't leave the page; the sidebar also receives desensitized plain text.
Q: Will there be a popup confirmation before the model operates?
A: Most actions default to "auto-share" without popup; clicking, input, keystrokes, navigation, refresh, cross-origin browser_navigate will popup by origin (once/session/permanent trust). Privacy-sensitive users can switch "Share page content" to "Ask every time" or "Off" in the sidebar settings.
Q: How to troubleshoot "Sidebar consistently shows not connected"?
A: First confirm dsh is running (default http://127.0.0.1:3080), access http://127.0.0.1:3080/ext/bridge-config in browser, should return JSON like {"wsUrl":"ws://127.0.0.1:3080/ext/bridge"}; if it returns a webpage, dsh started before the bridge was registered - restart dsh and refresh the page. Extension auto-detects ports 3080/3081/3090; if dsh runs on another port or is deployed remotely, fill in address and token in sidebar settings.
Q: Can the model see screenshots?
A: No screenshots are sent. The entire pipeline uses plain text: page is converted to structured text + numbered interaction list, and the model operates precisely via numbers. The advantage is stable numbering that doesn't change across snapshots, narrower privacy boundary; the disadvantage is that captchas, pure image buttons and other elements without accessible names will have the tool result note "elements without text accessible names exist", requiring manual completion.
Q: How to uninstall?
A: On the bridge plugin side, use dsh plugin --profile web remove @yuxianglin/dsh-bridge-browser; on Chrome side, go to chrome://extensions, find "dsh Browser Assistant", click "Remove". Deleting ~/.dsh/dsh-browser (hosted installation) and ~/.dsh/browser-extension (extension directory) will clear local copies.
Learning Curve
Entry Level — users only need to run the installation script once, load the extension, and click the whale icon; configuration only needs to be touched when upgrading DSH or deploying remotely.
Known Issues and Limitations
- Only one extension connection at a time: Later-connected extensions will replace earlier ones, and in-flight tool calls from the earlier extension will be settled with
bridge-closed. - Token doesn't auto-rotate: After generation, it's persisted in
~/.dsh/ext-bridge-tokenand doesn't expire; if reset is needed, manually delete that file. browser_pressdoesn't trigger browser native default behaviors: Synthesized Tab focus movement, arrow keys, Enter activation, etc. don't trigger, only serve as in-framework keyboard events; for scenarios depending on native behavior, manual operation is recommended.browser_waitdoesn't observe continuous DOM updates: Based on load completion + fixed silent window, continuously refreshing SPAs may be misjudged as stable.- Captcha / pure image buttons cannot be handled: Tool results will note "elements without text accessible names exist", requiring manual user completion.
- Cannot operate protected pages: Browser-built-in or extension pages like
chrome://, Chrome Web Store cannot have content scripts injected. - Depends on same DSH version line: Bridge plugin pins all
@deepseek-ai/dsh-*dependencies to 0.1.0-rc.6; when DSH upgrades, manifest and lock files need to be synced and root directory tests re-run. - Tab binding granularity is per extension connection: Within one extension connection, a single controlled tab is shared, not split by conversation sessions.
English | 中文
Connect DeepSeek Harness to the Chrome tab you are already using. The model can read page content, click controls, fill forms, scroll, and navigate while preserving your login state, session, and cookies. A side panel 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 MV3 extension as one standalone pnpm workspace.
The integration is text-only: pages become structured text with a numbered inventory of interactive elements, and the model addresses those elements by number. Screenshots never enter the model-facing pipeline.
The workspace uses a pinned, publicly available @deepseek-ai/dsh release for reproducible installation. It requires neither a DeepSeek Harness source checkout, dependencies from a parent directory, nor npm credentials. DeepSeek Harness is currently a developer preview, so upgrades may require coordinated dependency and API updates.
[!IMPORTANT] The unscoped
dsh-browserpackage 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 installation method below.
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 |
| Click element | browser_click | Click links, buttons, checkboxes, and other controls by inventory number |
| Fill forms | browser_type | React/Vue-compatible input; replace clears the field first |
| Press keys | browser_press | Keyboard events such as Enter, Tab, Escape, and arrow keys |
| Scroll | browser_scroll | Viewport scrolling: up, down, top, and bottom |
| Navigate | browser_navigate / browser_back / browser_forward / browser_reload | Navigation inside the controlled tab, with login state preserved |
| Read region | browser_get_text | Lazy-loaded or partial page text |
| Wait for stability | browser_wait | Page-load and render-settle detection |
Repository layout
packages/browser/bridge-browser/
cordis.patch.yml
extensions/dsh-browser/
scripts/install.sh
Why this design
- Your real browser, not a headless copy: the model works in the page you already have open, retaining logins, sessions, and cookies.
- A text-first model interface: numbered controls, stable IDs across snapshots, delta updates, and masked sensitive values make pages operable without vision.
- A narrow privacy boundary: passwords and payment-card values are always rendered as
••••and never leave the page. - A guarded bridge: authenticated handshakes protect remote connections, privileged gateway methods reject non-loopback callers, and the extension binds tools to one user-controlled tab.
Zero-configuration install and use
Prerequisites: Node.js ^22.19 or >=24, Corepack/pnpm, and Google Chrome. All required @deepseek-ai packages are available from the public npm registry; installation does not require an npm token.
Step 1 — install the bridge and extension. The recommended command does not require Git or a local clone:
curl -fsSL https://raw.githubusercontent.com/Lum1104/dsh-browser/refs/heads/main/scripts/install.sh | bash
The remote installer downloads main into the installer-managed directory ~/.dsh/dsh-browser, then installs the pinned public npm dependencies from the lockfile, builds the bridge plugin, registers its official bundle in dsh's local web profile, builds the extension, copies it to ~/.dsh/browser-extension, and opens chrome://extensions. Enable Developer mode and load the extension directory when prompted. Running the same command again updates the managed installation; keep source edits in a clone instead.
Already running dsh? Restart it after installing. The installer registers the bridge bundle in dsh's local web profile, and dsh loads its profile only at startup. An instance started before the install keeps running without the bridge, so the side panel reports "Not connected" even though the extension loaded correctly. Stop that instance and start it again (Step 2); the extension then discovers the bridge automatically and needs no reconfiguration.
Developers can clone the repository and run the same installer from any checkout. This mode uses the current branch without downloading or overwriting source files:
git clone https://github.com/Lum1104/dsh-browser.git
cd dsh-browser
./scripts/install.sh
Step 2 — start dsh. For a managed installation, use its pinned version:
cd ~/.dsh/dsh-browser && pnpm start
From a clone, run pnpm start in the repository root instead.
Or run the latest public release directly from npm:
npx @deepseek-ai/dsh web
Both commands load the same browser bundle from the local web profile. Port 3080 is used by default; if it is occupied, run pnpm start -- --port <port> or npx @deepseek-ai/dsh web --port <port>. When the DeepSeek whale icon appears in the toolbar, click it to open the side panel.
For subsequent use, the extension does not need to be installed again. Run either startup command above.
No configuration is required for local use: the extension discovers dsh through /ext/bridge-config, and loopback connections do not require a bridge token. This runtime security token is unrelated to npm authentication; an address and bridge token are only needed for remote deployment with --host 0.0.0.0.
Step 3 — use it: open any normal http:// or https:// page and click the DeepSeek whale icon. When the side panel reports "Connected", chat normally or click "Read page" first. A page that was already open before the extension was installed or reloaded is instrumented automatically on the first action; no page refresh is needed. Browser-internal and protected pages such as chrome:// and the Chrome Web Store cannot be read or operated.
To update a managed installation, run the same curl | bash command again. To update a clone, pull or switch to the desired revision and run ./scripts/install.sh. Then click Reload for "dsh Browser Assistant" in chrome://extensions and reopen the side panel. Chrome should load ~/.dsh/browser-extension; do not load the source directory extensions/dsh-browser/. If dsh web is already running, restart it too so it reloads the updated web profile (see Troubleshooting).
Troubleshooting
Side panel stays "Not connected"
- Make sure dsh web is running locally (default
http://127.0.0.1:3080). - Verify the bridge is loaded: open
http://127.0.0.1:3080/ext/bridge-config. It should return JSON such as{"wsUrl":"ws://127.0.0.1:3080/ext/bridge"}. If it returns a web page instead of JSON, the running dsh predates the bridge registration — restart dsh and refresh the page; the extension reconnects on its own. - The extension probes ports 3080, 3081, and 3090 automatically. If dsh runs on another port — or you use a remote
--host 0.0.0.0deployment — set the address (and bridge token) in the side panel settings.
Development
The bridge plugin and Chrome extension are both members of this repository's workspace. Run all commands from the repository root. For the first development installation, run pnpm install.
pnpm run build
pnpm run typecheck
pnpm run test
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 test
Notes:
- The bridge plugin must have a built
lib/before startup because the loader consumes it; bothscripts/install.shand the rootpnpm run buildbuild the plugin before the extension. - The dependencies of
@deepseek-ai/dshand 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.
Security
- The bridge path sits outside the
/apitrust boundary and performs its own bearer-token authentication. - Privileged gateway methods such as
settings.*,credentials.*, andhost.open*reject non-loopback sources. - The model-facing pipeline is text-only; passwords and payment-card values never leave the page.
- When work begins, the assistant binds to the active tab (at prompt submission, or at the first direct browser-tool call). If you switch tabs manually, later browser actions pause and the side panel asks whether the assistant should continue on the original tab or follow the new one. Choosing the original tab permits background operation; the extension never silently retargets or changes your visible tab. Closing the controlled tab also pauses tools until you explicitly select the current page.
- Page-authored text is wrapped as untrusted input. The default
automode reads only the controlled tab without an extra prompt; privacy-sensitive users can selectaskfor per-read confirmation oroffto block reads entirely. Inaskmode, the read dialog can allow one read or persistently switch back toauto; this can be reversed in Settings. Read page text is sent to the selected model. - Click, type, keypress, navigation, history, and reload calls fail closed until the user approves them. An origin may be trusted for the current side-panel session (cleared when the last panel closes or the service worker restarts), while permanent trust is managed explicitly in Settings. Explicit cross-origin
browser_navigatecalls and unknown history destinations always prompt again.
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](https://deepseek-plugin.org/plugins/Lum1104/dsh-browser)Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.