dsh-screenshot-macos
Manifest validScreenshot button for the DeepSeek Harness composer on macOS — drag-select a region, get an attachment.
dsh-screenshot-macos
A screenshot button for the DeepSeek Harness composer on macOS: drag-select any region of the screen and the image lands in the draft as an attachment, ready to send with your message.

Why
Pasting a screenshot into an agent conversation is a normal part of asking a question about a UI, an error, or a chart — but it usually means switching to another capture app, saving a file, and hunting for it in a file picker. This plugin puts native region capture directly in the composer:
- Two modes — capture without the DSH window in the shot (default), or keep the window visible and capture it too.
- Keyboard-first —
⌃⌥⌘1and⌃⌥⌘2start a capture from anywhere in the window. - No external app — a small ScreenCaptureKit helper is compiled on first use and runs from the plugin's cache directory.
- Same path as a paste — the PNG becomes a real composer attachment, so thumbnails, previews, and sending behave exactly like a pasted image.
- Local only — no network requests, no telemetry, no upload service.
Install
Requirements: macOS 14 or newer, DeepSeek Harness 0.2.2-rc.3 or newer, and the Xcode Command Line Tools (or Xcode) so the helper can be compiled on first use:
xcode-select --install
From the Plugins page (recommended)
- Open Plugins in the DSH sidebar.
- Choose Add plugin → Install a third-party plugin.
- Enter
dsh-screenshot-macosand confirm with Install. - Restart DeepSeek Harness if the page asks for it.
- On the first capture, allow Screen Recording for DeepSeek Harness when macOS asks.
The bundle is enabled on install. If the button does not appear, check that the plugin is switched on in Plugins → Installed and restart.
From the command line
dsh plugin --profile desktop add dsh-screenshot-macos
dsh plugin forwards to pnpm inside the profile; enable the bundle on the Plugins page afterwards, then restart.
From GitHub
dsh plugin --profile desktop add git+https://github.com/zhaoyanbo1/dsh-screenshot-macos.git
Or point Add plugin → Install a third-party plugin at a local clone of this repository (the path form is useful for development, since your edits load directly).
Usage
The button sits in the composer tool row, to the right of +. Click it to capture with the current mode; click the small arrow or right-click the button to switch modes.
| Mode | What ends up in the image | Shortcut |
|---|---|---|
| Capture without this window (default) | The screen below the DSH window — DSH itself is not in the shot | ⌃⌥⌘1 |
| Capture with window visible | The screen as displayed, including the DSH window | ⌃⌥⌘2 |
The screen freezes and dims; drag a region, then press Return to confirm. Esc, a right-click, or a 5-minute timeout cancels. Drags smaller than 8×8 points are ignored as accidental clicks. The image is inserted into the draft, not sent — add your text and press send when ready.
How it works
| Path | Role |
|---|---|
index.js | Host half. Serves same-origin routes under /dsh-screenshot-macos, compiles and runs the native helper, keeps the last 20 captures. |
native/dsh-snip.swift | The selector: ScreenCaptureKit freeze frame, one borderless panel per display, dim layer, selection, size badge, PNG export. |
client.js | Client half. Registers the button in conversation.input.left, portals the menu and notices, turns the PNG into a composer attachment. |
cordis.patch.yml | Bundle patch that inserts the plugin row. |
The helper is compiled once to ~/Library/Caches/dsh-screenshot-macos/dsh-snip (xcrun swiftc -O -parse-as-library) and recompiled when native/dsh-snip.swift changes. "Without this window" captures the content below the DSH window with CGWindowListCreateImage(.optionOnScreenBelowWindow), so the window is never actually hidden and there is no hide animation to wait for.
Read docs/DETAIL.md for the full design, routes, and implementation notes.
Troubleshooting
| Symptom | Fix |
|---|---|
| The button is missing | Enable the bundle in Plugins → Installed, then restart DSH. |
| "Screen Recording permission is required" | System Settings → Privacy & Security → Screen Recording → enable DeepSeek Harness, then relaunch the app. |
| "The capture helper is unavailable" | Install the Command Line Tools: xcode-select --install. The first capture can take 10–30 seconds while swiftc builds the helper. |
| The first capture is slow | Expected: the helper is compiled on first use. Later captures start in well under a second. |
| A region is black or empty | Some DRM-protected players and secure windows cannot be captured by ScreenCaptureKit. |
| Stale images or logs | Delete ~/Library/Caches/dsh-screenshot-macos/; it is rebuilt on the next capture. |
Client diagnostics are appended to ~/Library/Caches/dsh-screenshot-macos/diag.log; the Host also reports helper state at GET /dsh-screenshot-macos/status.
To remove the plugin, uninstall it on the Plugins page and optionally delete the cache directory above.
Privacy
Screenshots are written to ~/Library/Caches/dsh-screenshot-macos/captures/ and served to the DSH web UI over a same-origin localhost route. The plugin makes no outbound network requests and collects no telemetry. Once you send a message, the image is handled by DSH like any other attachment.
Development
git clone https://github.com/zhaoyanbo1/dsh-screenshot-macos.git
cd dsh-screenshot-macos
node --check index.js
node --check client.js
node scripts/check.mjs # manifest, locales, docs, market index
node scripts/market-index.mjs # regenerate market/index.json for a release
To compile the selector by hand:
xcrun swiftc -O -parse-as-library -o /tmp/dsh-snip native/dsh-snip.swift \
-framework AppKit -framework ScreenCaptureKit -framework CoreGraphics \
-framework ImageIO -framework UniformTypeIdentifiers -framework CoreText
Debug helpers, both opt-in:
- Start DSH with
DSH_SCREENSHOT_DEBUG=1to letPOST /dsh-screenshot-macos/captureaccept adebugRect({x, y, width, height}) and skip the interactive selection. - With the web console open,
window.__dshScreenshot.run('hide' | 'keep')re-runs a capture and.report()posts client diagnostics to the Host log.
CI compiles the Swift helper on macos-26 and runs the manifest checks on every push.
Plugin markets
This repository publishes a format-1 DSH plugin index:
https://zhaoyanbo1.github.io/dsh-screenshot-macos/index.json
Add it in Plugins → Discover → Add index source to install and update from Discover. The package is also prepared for the community awesome-dsh-plugin catalog.
License
Comments
Loading…