zhqowo/dsh-whale-tray

English | 中文

One-click start/stop for DeepSeek Harness (dsh) — a system tray app on Windows, a menu-bar app on macOS. Runs as an independent process, like a Steam launcher for dsh.

🦞 Looking for the OpenClaw Lobster? It now lives in its own repo: zhqowo/openclaw-menubar — the two serve different audiences, so splitting them lets each be discovered and released on its own.

Which one do I want

Platform	Program	Shape	Source
Windows	大肥鱼.exe	system tray (bottom-right)	WhaleTray.cs
macOS	大肥鱼.app	menu bar (top-right)	macos/

Feature comparison

Action	Windows	macOS
Toggle service	right-click → start/stop	same
Wake the Web UI	left / double-click the whale	left click
Switch to the existing tab	port 9335 + companion extension	AppleScript, no extension needed
Restart service	right-click → restart	same
Top-up page	right-click → top-up	same
Exit	stops dsh first, then exits	same
State refresh	every 2 s	every 3 s (TCP probe)
Shape	tray + hidden console	menu bar, silent by nature

The macOS build needs no browser extension — Chromium browsers expose their tabs to AppleScript, so we just select the tab. Only Windows needs the port-polling + extension combo.

⚠️ macOS has a trap Windows doesn't: TCC permissions. Before changing code, moving machines, or rebuilding, read the TCC section of macos/README.md. Its three rules were paid for in debugging time — violating any of them silently kills every permission the app has.

---

🐳 Da Fei Yu

Windows build

Action	Behavior
Double-click exe	Whale icon appears in the tray; auto-starts dsh if not running (hidden, logs to dsh-tray.log)
Left / double-click the whale	Brings up the DSH Web UI (switches to the background tab via the companion extension — no duplicate tabs)
Right-click → Toggle	Switch dsh on/off; state refreshes every 2 s
Right-click → Restart	Shown only while dsh runs; stops the old service → waits for the port → restarts hidden
Right-click → Top-up	Opens https://platform.deepseek.com/usage in Edge
Right-click → Exit	Stops the dsh service first, then exits

Tech highlights (Windows)

• Independent process: does not depend on dsh; force-killing the whale does not affect dsh and vice versa
• Wake-up, three layers: ① window-title match (foreground tab) ② extension switches the background tab (recommended) ③ fallback: open a new tab
• Extension channel: local port 9335 (whale signals → extension polls → chrome.tabs.update + windows.update(state:'normal'))
• DPI: PerMonitorV2 awareness + system menu font (app.manifest)
• Handle safety: listener socket marked non-inheritable; 20 s self-healing rebind when the port is taken
• Single instance: mutex prevents duplicate runs

Build (Windows)

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe /nologo /target:winexe /out:DaFeiYu.exe /win32icon:whale.ico /win32manifest:app.manifest /codepage:65001 /r:System.dll /r:System.Drawing.dll /r:System.Windows.Forms.dll /r:System.Web.Extensions.dll /r:UIAutomationClient.dll /r:UIAutomationTypes.dll WhaleTray.cs

Extension setup (one-time)

1. Open edge://extensions → enable Developer mode
2. Click Load unpacked → select the extension/ folder
3. Clicking the whale now silently switches to the DSH tab

macOS build

A Swift + Cocoa NSStatusItem app. A whale in the menu bar: left click switches to the DSH tab, right click opens the menu (status · toggle · restart · open web · top-up · quit); full colour while running, dimmed while stopped.

One-command install (recommended)

curl -fsSL https://raw.githubusercontent.com/zhqowo/dsh-whale-tray/main/macos/install.sh | zsh

It locates your dsh, installs the app into /Applications, drops the dsh-ctl.sh service script, writes the config, and finishes with a health check. dsh somewhere else? --dir. Not port 3080? --port. Not Edge? --browser "Google Chrome".

# run from a local checkout instead
zsh macos/install.sh --dir ~/code/DeepSeekHarness --port 3100 --browser "Google Chrome"

If all you want is "start it with one click, open the UI", you are done — the only thing you must click is the one-time "Da Fei Yu wants to control Microsoft Edge" Automation prompt.

Build it yourself (when hacking on the code)

WHALE_APP_OUT=/tmp/staging/DaFeiYu.app zsh macos/build.sh   # staging: your Desktop copy is untouched

⚠️ zsh macos/build.sh without WHALE_APP_OUT overwrites and rebuilds ~/Desktop/大肥鱼.app — which changes its cdhash and invalidates every TCC permission. Always use staging while developing.

Details — config keys, the doctor health check, --print-url debugging, why this cannot be installed like a plugin, the four tiers of feature trimming, icon composition, left/right click separation, AppleScript gotchas, and the must-read TCC permission section — live in macos/README.md.

---

⚙️ Configuration (optional, both platforms)

It works with no configuration at all — the defaults target a standard DeepSeek + dsh setup.

The menu's Top up entry opens https://platform.deepseek.com/usage by default. But this launcher only starts/stops the dsh service — it has nothing to do with which model provider you use, and you are free to run something other than DeepSeek.

Drop a JSON file and you can repoint it without recompiling:

The DSH_WHALE_TRAY_CONFIG environment variable overrides the path on either platform.

{
  // page the billing entry opens
  "billingUrl":   "https://your-provider.example/billing",
  // text shown for that menu item (default: 充值)
  "billingLabel": "Billing",

  // Windows only: where your dsh is installed.
  // Left out, it probes D:\DeepSeekHarness, then %USERPROFILE%\DeepSeekHarness
  "dshHome":      "C:\\DeepSeekHarness",

  // macOS only: where your dsh is installed / the port / which browser to drive.
  // The menu-bar app and dsh-ctl.sh read the same file, so one place is enough.
  "dshDir":       "~/DeepSeekHarness",
  "port":         3080,
  "browser":      "Microsoft Edge"
}

key	default	what it does
billingUrl	https://platform.deepseek.com/usage	page the billing entry opens
billingLabel	充值	label of that menu item
dshHome	auto-detected	Windows only: dsh install root
dshDir	~/DeepSeekHarness	macOS only: dsh install root
port	3080	macOS only: DSH port
browser	Microsoft Edge	macOS only: which browser AppleScript drives
logPath	<dshDir>/dsh-web.log	macOS only: where the ?token= is harvested from (required on 0.1.7+)
workdir	<dshDir>/projects	macOS only: cwd when starting dsh
ctlPath	<dshDir>/bin/dsh-ctl.sh	macOS only: service script location, rarely needed

• Every key is optional — set only the ones you care about
• Missing file / malformed JSON / wrong type → silently falls back to the defaults; the tray or menu bar must never fail to come up over an optional config
• The CLI (macos/dsh-ctl.sh billing) reads the same file
• macOS dsh-ctl.sh also honours environment variables (they win over the file): DSH_DIR DSH_PORT DSH_LOG DSH_BIN DSH_WORKDIR DSH_BROWSER DSH_BILLING_URL
• JSON comments are not supported — the block above is marked jsonc only to allow annotations

---

🦞 OpenClaw Lobster → moved to its own repo

The OpenClaw gateway menu-bar toggle used to live here. It has moved to:

👉 zhqowo/openclaw-menubar

Source, build scripts, icon assets and releases all live there now. The old openclaw/ directory was removed from this repo.

---

Install as a DSH plugin (manifest only, not the app)

This repo declares a dsh.bundle manifest, so dsh plugin add recognises it:

dsh plugin --profile web add github:zhqowo/dsh-whale-tray

⚠️ This does not install the menu-bar app on your Mac. It only registers the repo in your profile so the plugin market / find_dsh_plugin can find it. Four things block a true one-step install: ① desktop apps cannot be distributed over npm ② ad-hoc signing gets stopped by Gatekeeper ③ TCC grants cannot be automated ④ install path, port and browser differ per machine. The full explanation, what you need to do locally, and how to trim features are in macos/README.md.

To actually install it, use the one-command curl above.

Downloads

Use Releases, or the one-command installer above.

Where	File	What
Releases	DaFeiYu.app.zip	macOS menu-bar version; install.sh pulls this stable URL
dist/	大肥鱼.app.zip	legacy archive, kept as-is

🦞 The OpenClaw Lobster download lives in the new repo: openclaw-menubar/releases

Because they are ad-hoc signed, Gatekeeper blocks the first launch: right-click → Open, or xattr -dr com.apple.quarantine /Applications/大肥鱼.app. ⚠️ Do not rebuild 大肥鱼.app yourself — a rebuild changes its cdhash and invalidates every TCC permission it holds. Upgrading to a new release changes it too: if screenshot / UI control starts reporting a permission error, remove the app from the privacy list and add it back.

Layout

WhaleTray.cs      # Windows main program (C#, WinForms, .NET Framework 4.x)
app.manifest      # Windows DPI awareness manifest
extension/        # Windows companion extension (wakes the background DSH tab)
whale*.*          # Windows icons (cut-out + resized + small-size white-hair fix)
macos/            # macOS Da Fei Yu (Swift) + install.sh + dsh-ctl.sh
tools/            # Helper tools (check-perms.sh health check / uictl UI automation)
dist/             # Packaged macOS .app bundles
package.json      # dsh plugin manifest (declares dsh.bundle for `dsh plugin add`)
cordis.patch.yml  # the patch file that manifest points at

🦞 The OpenClaw Lobster moved to zhqowo/openclaw-menubar.

🖼️ Artwork credit

I did not draw the whale — here is where it comes from. Every icon on both platforms is derived from that one original.

• Original artist: Yue Jiang (月匠, Bilibili) — the whale-girl artwork was drawn by the Bilibili artist Yue Jiang (source image: whale-source.png, from their Bilibili post)
• Obtained via the dsh-whale-widget plugin — MeteorNOX/DeepSeek-Balance-Whale-Widget (MIT License, Copyright © 2026 MeteorNOX)
• If Yue Jiang would like the credit adjusted, or the artwork replaced or removed, please open an issue and it will be handled immediately

No artistic changes were made — only mechanical ones:

File	Platform	How it was produced
whale.ico	Windows	cropped → resized to 16/32/48/256 → packed as ico
whale16/32/48/256.png	Windows	the same, as individual size files
macos/whale256.png	macOS	the original downscaled to 256 (the build's starting asset)
menu-bar whale.png / whale@2x.png	macOS	the above via sips -z to 22px / 44px
the app icon AppIcon.icns	macOS	the above laid over a gradient card (icon_compose.swift), converted to icns

Small sizes get a white-hair brightening pass — shrunk to 16px the original's lines smear into a dark blob; brightening them is what makes it legible.

The macOS 22px icon has its own trap: NSImage(contentsOfFile:) does not auto-load the @2x sibling, so a single rep looks fuzzy on Retina. The build script ships both.

Full third-party asset notice: NOTICE.

Requirements

• DeepSeek Harness (dsh)
• Windows: Edge or Chrome installed (for the wake-up feature)
• macOS: Edge or Chrome installed (for tab switching); see macos/README.md for the dsh side

License

MIT © 2026 zhqowo — use it, change it, ship it commercially; just keep the copyright notice.

⚠️ Artwork is the exception: the whale artwork is © Yue Jiang (月匠, Bilibili) — see the "Artwork credit" section above for the attribution chain. Keep that credit if you redistribute.