dsh-pip

One click detaches the DeepSeek Harness web GUI into an always-on-top Document Picture-in-Picture window — it floats beside your editor, and one more click puts it back.

English · 中文

Why

The DSH web GUI lives in a browser tab — watching the agent while writing code means hopping between the editor and the tab. dsh-pip uses Document Picture-in-Picture to move the whole app (not a screenshot) into a system-level always-on-top window:

• One command to install. The package ships a bundle patch (dsh.bundle.patch): dsh plugin add mounts the plugin row automatically — no file edits.
• Zero config. Restart dsh web and a floating "独立窗口" button appears in the corner of the UI. Click it, done.
• Window matches the browser by default. The detached window opens at the current tab's viewport size; pin it with two numbers if you prefer.
• The whole app comes along. On click, #root moves together with styles and theme — not a screencast, the app itself, fully interactive.
• No-op where unsupported. Safari / Firefox lack the Document PiP API; the script no-ops and no button ever appears.

dsh-pip vs DeepSeek Harness Desktop

These projects solve different layers of the same workflow. dsh-pip is a focused plugin for people who already run dsh web and only want the UI beside their editor; DeepSeek Harness Desktop is a packaged Electron distribution that owns the desktop app and local Harness service lifecycle.

Choose dsh-pip if your current Harness setup already works and you want the smallest change: keep your runtime, browser, profiles, and update flow, and add only a floating window. Choose Desktop if you want Harness packaged and managed as a desktop application without setting up Node.js or starting it from the command line.

Quick start

dsh plugin --profile web add dsh-pip

Restart dsh web — done, zero config:

• the bundle patch mounts the plugin row and injects the browser script into every page response — purely additive, core rows untouched;
• open the web UI, click the floating "独立窗口" button to detach;
• close the window (or click its "返回标签页" button) and the app returns to the tab.

How it works

On click the browser script calls documentPictureInPicture.requestWindow() during the click's transient activation, copies the opener's stylesheets and theme attributes into the new window, adopts the app root (#root) into it, and hides the opener button. The window's pagehide event — fired by the browser's built-in "back to tab" control or the script's "返回标签页" button — moves the root back and restores the button.

Configuration

All optional — the defaults just work. Override them in the profile's ~/.dsh/profiles/web/cordis.patch.yml:

- id: pip
  config:
    enabled: true
    width: 1280   # pin the size with numbers
    height: 800

requestWindow width/height are hints — Chromium clamps the window to the available screen, so a maximized browser may yield a slightly smaller window.

Requirements

• Chromium 116+ (Chrome, Edge). The Document Picture-in-Picture API does not exist in Safari or Firefox; the script no-ops and no button appears.
• The webServer service, which the web profile provides through its @deepseek-ai/dsh-host-webserver bundle.

Install & lifecycle

Install

dsh plugin --profile web add dsh-pip

To install an unpublished checkout (e.g. during development), pass a local path:

dsh plugin --profile web add file:/path/to/dsh-pip

Disable / restore

- id: pip
  disabled: true

Flip it back to false to restore.

Update

dsh plugin --profile web update dsh-pip

Remove

dsh plugin --profile web remove dsh-pip

Removes the dependency and the bundle layer; nothing is left behind.

Known limitations

• Chromium-only — Safari and Firefox never show the button.
• Portal surfaces stay in the tab — the app renders menus, modals, toasts, and hover cards through createPortal(..., document.body); those elements continue to target the original tab's body while detached, so they are invisible until the app returns. Detaching is best used for reading/steady state, not for opening menus in the floating window.
• Window-scoped listeners stay home — global window/document listeners (keyboard shortcuts, scroll tracking) keep firing in the original tab; only React-managed events on the moved root follow the window.

Development

npm install
npm run typecheck   # tsc --noEmit
npm run build       # tsc → lib/ + copy src/client.js → lib/client.js

prepack (run by npm pack / npm publish) rebuilds before packaging so the published tarball always ships a current lib/.

License

MIT