🐋 DeepSeek Harness

August 30, 2026 · View on GitHub

🐋 DeepSeek Harness — Desktop

A native macOS desktop shell for DeepSeek Harness — double-click, no terminal.

✨ What this is

DeepSeek Harness is powerful, but starting it means opening a terminal and typing dsh web. This app wraps it in a thin Electron shell — double-click, and it boots dsh --profile web --no-open --port 0, waits for the local URL, and renders the exact same Web GUI in a native window. Every web feature, zero divergence, zero terminal.

🖥️ No terminal	🐋 Live tray	🎯 Busyness-aware	🌗 Light/dark	🔄 Auto-update
Double-click to run	Two switchable icon styles	The icon reacts to real workload	Adaptive icons	GitHub Releases

🐋 The tray icon — alive and switchable

The menu-bar icon is not a static glyph. It reflects what DeepSeek Harness is doing:

Idle → a calm, still icon.
Working → an animated icon whose speed follows how busy the backend is (running sessions + running jobs).

Right-click the icon to switch between two styles:

Style	Idle	Working
🐟 Fish Swing (default)	Still whale	Swinging whale — faster with more work
🔮 Thinking Orb	Search globe	Listening orb — a rippling dot sphere

Both styles adapt to light/dark menu bars automatically, and your choice is remembered across launches.

_{🐟 Fish Swing}

_{🔮 Thinking Orb}

Busyness → animation

Busyness	State	Frequency
0	Still	—
1	Light	Slow (~1.8 s/cycle)
2	Medium	Medium (~1.2 s/cycle)
3	Heavy	Fast (~0.8 s/cycle)

Busyness = running sessions + running jobs, read live from the harness's own event streams.

Swing amplitude

Right-click the menu-bar icon → Swing Amplitude → pick a preset:

Preset	Subtle	Default	Strong	Stronger	Strongest
Rotation	6°	9°	12°	15°	18°

🚀 Getting Started

double-click the .app — or drop it into Applications. If macOS warns on first launch (unsigned build), right-click → Open.

Left-click the tray icon → show the window
Right-click → Open / Quit / Icon Style / Swing Amplitude
Red close button → hides to the tray; the app keeps running in the background

🔧 How it works

DeepSeek Harness.app
  └─ Electron main process
       ├─ resolve dsh (DSH_BIN override → /opt/homebrew/bin/dsh → … → PATH)
       ├─ spawn: dsh --profile web --no-open --port 0
       ├─ parse stdout:  "dsh web: http://127.0.0.1:<port>"
       ├─ BrowserWindow.loadURL(that URL)
       └─ lifecycle: SIGTERM on quit · retry dialog on backend crash

The backend binds 127.0.0.1 on an OS-assigned port, so the /api loopback trust fence passes with no extra configuration and there is no fixed-port conflict.

⚠️ Do not open the same session in a separate terminal dsh web at the same time — the session store is single-writer, so two live backends writing one session log can corrupt it (history then fails with corrupt session log: seq gap in committed region).

📦 Develop / package

npm install          # installs electron + electron-builder
npm start            # run from source
npm run pack         # build the .app (release/mac-arm64/DeepSeek Harness.app)
npm run dist         # also build .dmg and .zip

Output lands in release/. If a Developer ID Application certificate is in your Keychain, electron-builder signs automatically; otherwise the app is left unsigned for local use.

🔏 Code signing & notarization (remove Gatekeeper)

Signing + notarization require an Apple Developer Program membership and a Developer ID certificate. The toolchain and build config are already wired up — you only supply the credentials.

One-time setup

Join the Apple Developer Program (paid).
Create a Developer ID Application certificate: Xcode → Settings → Accounts → Manage Certificates → + → Developer ID Application. Verify with security find-identity -v -p codesigning.
Create an App Store Connect API key (Developer role): App Store Connect → Users and Access → Integrations → App Store Connect API → Team Keys → generate → download the .p8 → note the Key ID and Issuer ID.

Build + notarize

npm run pack    # signs automatically once the cert is in Keychain

APPLE_API_KEY_PATH=~/.appstoreconnect/AuthKey_XXXXXX.p8 \
APPLE_API_KEY_ID=XXXXXXXXXX \
APPLE_API_ISSUER_ID=00000000-0000-0000-0000-000000000000 \
./scripts/notarize.sh

🔄 Auto-update (GitHub Releases)

The app checks for updates on launch (then hourly) and offers Restart now when a newer version is out. Publish a new release with a GitHub token:

GH_TOKEN=github_pat_xxx ./scripts/publish.sh

Note: reliable macOS auto-update is best with a signed app; for an unsigned personal build it is best-effort.

⚙️ Configuration

Variable	Purpose
`DSH_BIN`	Absolute path to the `dsh` executable (defaults to `/opt/homebrew/bin/dsh`).
`DSH_HOME`	Inherited from the environment; shares `~/.dsh` profiles, credentials, and sessions with the CLI.

🗺️ Roadmap

v0.1 — Electron shell wrapping dsh web (full web parity)
Appearance-adaptive Dock icon (light/dark)
Busyness-aware animated tray + close-to-tray
Two switchable tray icon styles (Fish Swing / Thinking Orb)
Auto-update (GitHub Releases)
Code signing + notarization — config ready, pending Apple Developer credentials
Native IPC transport — load dist over file:// and bridge /api over ipcRenderer

Made with ❤️ for the DeepSeek Harness community.