Introduction¶

To let Agents do browser work, the common approach is to start a headless browser: the Agent clicks buttons, fills out forms, and sends screenshots and logs back to you. The entire process is close to a black box—pages fail to load, selectors become invalid, or get blocked by login prompts. You can only guess by looking at the logs, and there is no entry point to intervene.

dsh-plugin-chrome takes a different path: each DSH session opens a real, visible Chrome window. The screen content is streamed to the Web GUI in real-time. You watch the Agent operate beside you and can take over at any time by clicking a few times. Below is an introduction to its features, installation, and usage.

What is this¶

dsh-plugin-chrome is the browser visualization plugin for DeepSeek Harness (DSH), maintained by jiaererw, under the MIT license, and open-sourced on GitHub. It solves the problem: when an Agent operates on a browser, you can see what it is doing in real-time and intervene manually at any time.

DSH’s philosophy is “everything is a plugin”. Once this plugin is installed into a profile, a Chrome tab appears at the top of the session, and the Agent automatically gains a set of browser tools.

Core Features¶

One visible window per session¶

Each DSH session has one visible real Chrome window (non-headless), using an isolated user-data-dir, not mixed with daily browsing. Every step of the Agent’s operation can be seen directly.

Real-time screen streaming¶

The Chrome tab in the Web GUI streams the window content via Chrome screencast in real-time. Frame rate is smooth when the page is active. For idle pages, heartbeats act as a fallback to force capture frames—approximately one frame every 2 seconds after 3 seconds of silence. The screen will not freeze.

16 chrome_* tools¶

chrome_open / chrome_status / chrome_close / chrome_navigate
chrome_tabs / chrome_snapshot / chrome_screenshot / chrome_click
chrome_click_at / chrome_fill / chrome_type / chrome_press_key
chrome_hover / chrome_scroll / chrome_evaluate / chrome_wait

Among them, chrome_tabs covers four operations: list / create / close / select; snapshot, screenshot, and click always target the currently selected tab.

Snapshot and Screenshot¶

chrome_snapshot returns a compact accessibility tree with stable element UIDs. Clicks and fills target UIDs directly, which is much lighter than dumping the entire DOM and less prone to failure due to page structure changes.

chrome_screenshot has a dual-channel design: image chunks are sent into the model context so the model “sees” the page; meanwhile, they are saved to the panel’s session screenshot history. History entries retain title, URL, and dimension metadata, persisting across restarts.

Security Design¶

• CDP does not expose fixed ports;
• Web API rejects cross-site requests (based on Sec-Fetch-Site) and performs a whitelist check on sessionId;
• Browser data is isolated by session.

Resource Governance and Lifecycle¶

• Idle windows close automatically, defaulting to 10 minutes, configurable;
• chrome_close explicitly closes; when the plugin is uninstalled or the host closes, all windows opened by it will be closed;
• Lazy startup: Chrome only starts on the first chrome_* call or when the panel Open button is pressed;
• Orphan adoption: for Chrome left behind by a DSH crash, the plugin reconnects via DevToolsActivePort instead of failing with an error;
• Auto tab recovery: every operation ensures a usable tab exists, avoiding the situation where the window is full of chrome:// internal pages and cannot work.

Installation and Enablement¶

Prerequisites: DeepSeek Harness (DSH) is installed, Chrome or Edge is available on the machine; the plugin requires Node >= 20.

Official installation command:

npx -p @deepseek-ai/dsh dsh plugin --profile web add github:jiaererw/dsh-plugin-chrome

For local development, you can install using a local path:

npx -p @deepseek-ai/dsh dsh plugin --profile web add D:/harness/dsh-plugin-chrome

After installation, DSH needs to be restarted. A Chrome tab will appear at the top of each session.

Two potential issues to watch out for:

1. If there are still old manual mount lines for dsh-plugin-chrome in the profile’s cordis.patch.yml (added during local development), remove them before using the CLI installation to avoid double mounting;
2. pnpm’s strict-dep-builds might block installation: after adding dsh-plugin-chrome: true to the allowBuilds in the profile’s pnpm-workspace.yaml, retry.

Configuration¶

Configuration is done by overriding the plugin line in the profile’s cordis.patch.yml (complete replacement):

- id: dsh-plugin-chrome
  config:
    headless: false            # Keep false—the visible window is the point of this plugin
    executablePath: ''         # Leave empty to auto-detect Chrome/Edge, or fill with an absolute path
    idleTimeoutMs: 600000      # Auto-close on idle (0 disables)
    windowWidth: 1280
    windowHeight: 900
    screencastFrameSkip: 4     # Frame skipping (1 = smoothest)
    screencastQuality: 70      # JPEG quality 1-100
    maxSnapshotText: 60000     # Max characters in a single snapshot
    maxTabs: 16
    extraArgs: ''              # Additional Chrome startup arguments

Browser data and screenshots are stored in ~/.dsh/data/dsh-plugin-chrome/sessions/<sessionId>/, and can be overridden by dataRoot.

Typical Usage¶

To let an Agent execute a natural language instruction:

Open Chrome, go to https://example.com, take a screenshot, then click the “Login” button and fill in the username.

The corresponding tool flow is: chrome_open → chrome_navigate → chrome_screenshot (model sees image) → chrome_snapshot (get UID) → chrome_click / chrome_fill.

Operations on the panel side:

1. Open the Chrome tab at the top of the session, and the Live view continuously displays the window content;
2. The sidebar can create, switch, and close tabs, syncing with the real window;
3. You can manually click the real window to take over at any time; the Agent will see your changes on the next tool call;
4. Every chrome_screenshot is saved to the panel screenshot history; clicking the thumbnail enlarges it for viewing.

Handling some common situations:

• No need to reinstall after closing the window yourself; any next chrome_* call or the panel Open button will restart it;
• If the Agent reports “unknown uid”, it means the page has changed; let it run chrome_snapshot again;
• If the panel is black, first check if the window is running (check the top status), it takes a few seconds for the first startup.

Suitable Scenarios and Notes¶

Suitable for:

• Those who want to watch Agent’s browser operations in real-time and don’t trust pure log reporting;
• Those debugging browser automation workflows who need to see the scene rather than guess from logs;
• Tasks requiring login states—each session uses an isolated profile, so login states do not interoperate with daily browsers (by design). If login is needed, let the Agent complete it within the session, and the login state persists inside the session.

Notes:

1. Be careful using screenshots with text-only models. chrome_screenshot writes image chunks into the session history. If the model does not accept images, subsequent rounds will be rejected (UNSUPPORTED_CONTENT: does not accept image input) and the session will stop responding, making retries ineffective. For sessions requiring screenshots, use a model that supports vision, or avoid chrome_screenshot in that session;
2. The headless configuration should remain false; the visible window is the core of this plugin;
3. Security reminder: The plugin runs with the permissions of the current dsh process. Please check the source code and license yourself before installing. The community directory skillhub.cn mentioned in the text is an independent site and has no official affiliation with DeepSeek or Hypothesis.

Conclusion¶

dsh-plugin-chrome turns Agent’s browser operations from a black box into a live scene: the window is visible, the content is real-time, and takeover is possible anytime. With 16 tools and lifecycle safeguards, it can run stably for a long time within a session. If you are using DSH for browser-related tasks, it is worth installing.

• Directory: https://www.skillhub.cn/plugins/jiaererw/dsh-plugin-chrome
• GitHub: https://github.com/jiaererw/dsh-plugin-chrome