dsh-browser-control: A CDP plugin that lets DSH agents reuse your daily Chrome login state

Introduction¶

Connecting an agent to a browser usually involves spinning up a clean headless instance. The problem is the login state: many pages require logged-in Cookies to display real content, and re-logging in every time in an isolated environment is costly. Directly opening --remote-debugging-port on the Chrome used for daily work is explicitly prohibited by newer Chrome versions—the default user-data-dir does not allow opening the debugging port.

Below is an introduction to dsh-browser-control, a DeepSeek Harness (DSH) plugin that drives the browser using CDP (Chrome DevTools Protocol). Its core selling point is login state reuse: it moves your daily Chrome login state into an isolated debugging instance, allowing the agent to navigate, take screenshots, capture errors, and execute JS as a “logged-in” user.

What is this¶

dsh-browser-control is a DSH plugin maintained by PangYiMing, version 0.1.0, under the MIT license. It controls the browser via CDP and provides:

• Reuse of daily Chrome login state
• Page navigation and screenshotting
• Capture console / pageError / networkError
• Execute arbitrary JS on the page
• Mobile viewport and UA simulation

The plugin depends on ws ^8.18.0, with peerDependencies being @deepseek-ai/dsh-tools and @deepseek-ai/cordis, and requires Node >= 20.11.

Core Capabilities¶

Login State Reuse Launcher¶

scripts/launch.sh is responsible for starting a CDP debugging instance on port :9222. Instead of directly modifying the daily Chrome launch parameters, it:

1. Read-only copies the daily Chrome login state files (Cookies / Login Data / Local Storage / IndexedDB, etc.) to the isolated directory /tmp/chrome-e2e-profile;
2. Starts the debugging instance using this isolated directory.

A few design details:

• One-way, no write-back: The debugging instance will not pollute the daily Chrome data;
• Lazy sync: Only re-copies on the first run or when --refresh is specified;
• Port probing and reuse: Reuses the instance if it is already running, avoiding duplicate starts;
• Precise pkill: Only kills the debugging instance when closing, without harming the daily browser.

For principles and implementation details, see docs/cdp-login-reuse.md in the repository.

CDP Driver Script¶

scripts/drive.mjs handles specific browser operations: navigation / screenshot / console / eval / mobile simulation. After navigation completes, it outputs a JSON containing title, url (note this is the final address after SPA jumps), bodyPreview, console, pageErrors, networkErrors, and the screenshot path. In other words, a single navigation gives you the page text preview and three types of error information, making it easy for the agent to directly determine the page state.

Wrapped into 6 DSH Tools¶

After installing the plugin, the following browser_* tools are automatically registered into the agent’s tool set:

Installation¶

There are two ways. The npm command is only available after the plugin is published to npm:

dsh plugin --profile demo add dsh-browser-control

Or install directly from GitHub source code; source code installation requires the prepare build:

dsh plugin --profile demo add github:PangYiMing/dsh-browser-control

Typical Usage¶

At the script level, you can run these two files directly. First, start the debugging instance:

./scripts/launch.sh   # Start :9222 debugging instance (reuses daily Chrome login state; reuses if already running)

launch.sh also supports three parameters: --refresh / --kill / --status, corresponding to forcing re-sync of the login state, closing the instance, and viewing status.

Then drive the browser to navigate and screenshot:

node scripts/drive.mjs "<url>" \
  --out /tmp/shot.png \
  [--mobile] [--wait 4000] [--eval "<expr>"]

Three optional parameters:

• --mobile: 390x844 viewport + iPhone UA simulation;
• --wait 4000: milliseconds to wait;
• --eval "<expr>": Execute arbitrary JS on the page, which can be used to verify DOM state, read window globals, or call library APIs.

In the agent session, you don’t need to remember commands; you can trigger them with natural language:

browser_launch 起 Chrome，然后 browser_open 打开 https://example.com 截图给我看

Canvas Screenshot Pitfalls¶

If the page uses visualization libraries like G6 / echarts / D3 / WebGL to draw canvas, direct screenshotting might result in a blank image. The reason is that raf in background tabs is throttled, so rendering doesn’t run at all. The plugin’s handling is: create a new tab + Page.bringToFront + kick raf. The author also specifically reminds: do not use getImageData when checking if rendering is complete. Details see docs/cdp-canvas-pitfalls.md.

Use Cases and Considerations¶

Suitable scenarios: Letting the agent check pages requiring login, troubleshooting frontend errors (console / pageError / networkError captured all at once), verifying visualization page rendering results, and performing page checks under a mobile viewport.

Boundaries must also be clear. What is completed in the roadmap: login state reuse launcher, CDP driver, and 6 browser_* tools; not yet completed: click / form filling / form interaction, Playwright backend, multi-tab / multi-window management. In other words, currently it leans towards “seeing” and “reading,” it is not yet a complete browser operation solution.

Additionally, a reminder: the plugin runs with the permissions of the current dsh process. Before installation, it is recommended to check the source code and license (MIT, see ./LICENSE) in the repository first to ensure it meets your security requirements.

Conclusion¶

dsh-browser-control solves the most common login state problem when agents operate browsers, while packing navigation, screenshot, and error capture into a JSON output that can be obtained in one call. If you are using DSH for agent development and need an agent to “log in and view web pages,” you can give it a try.

• Directory: https://www.skillhub.cn/plugins/PangYiMing/dsh-browser-control
• GitHub: https://github.com/PangYiMing/dsh-browser-control