dsh-menubar-launcher
DSH Launcher 的主机插件：将运行中服务器的端口、PID 和令牌化 URL 发布为运行时描述符。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:songer522/dsh-launcher#bbc132d56c7719917f6b64752b53e6f05ca0ad31Menubar Launcher 以 dsh-menubar-launcher 发布，当前版本为 1.4.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English · 简体中文
[!IMPORTANT] Arrived from the plugin market? This plugin belongs to a macOS app. On its own it only writes a small JSON file describing the running server — that is deliberate, and it is all it does. The thing you actually interact with is a macOS menu bar app, built from this repository with
./build.sh. Install the app first; see Install. Not on macOS? The plugin runs anywhere, but nothing here will be useful to you without the app.
A tiny macOS menu bar utility for a local development server: start it, open it in your browser, restart it, or stop it — without touching a terminal.
It lives in the status bar with no Dock icon, so it stays out of your way.
Written for DeepSeek Harness
(pnpm dsh web), but the command, port, project folder and browser are all
configurable, so it works for any long-running local server.
Native AppKit, single Swift file, no dependencies.
It ships with a small companion DSH plugin so the app learns the server's port, PID and tokenized URL from the server itself rather than by reading its log. See DSH plugin.
https://github.com/user-attachments/assets/153503d2-c5b8-4d74-aaff-aa20f18bf6de
The itch was simple: every time I wanted to use DeepSeek Harness, running it from source meant running it from a terminal.
cd ~/Workspace/deepseek-harness
pnpm dsh web
The command itself is small — but the ceremony around it wasn't. The terminal tab had to stay open for the whole session; pulling new changes meant going back to it, killing the server, and starting it again; the URL with its per-process token had to be copied out of the logs; and when the session was over the server had to be stopped by hand or it kept squatting on the port.
All the actual work happens in a browser tab. The terminal was never the point of the tool — it was just the tollbooth in front of it. So I gave that ceremony a menu bar icon instead: one click to start, one click to open the browser, restart after an update, and a confirmed stop — with the server's state visible at a glance and no Dock icon in the way.
Trying to do this properly from a GUI app is also what surfaced the sharp
edges that the terminal had been silently papering over — a GUI app inherits no
shell PATH, DSH's launch token must survive into the opened tab, and stopping
must target only the process listening on the port. Those are documented under
How it works.
The status icon is the DeepSeek whale, drawn as a template image so macOS tints it for light and dark menu bars. It shows server state at a glance — solid when running, dimmed when stopped — and everything is one click away:
DSH Launcher menu open in the macOS menu bar, showing server status and actions
The two dimmed lines at the top are status, not actions: server state (Running on port 3080, Not running, or a transient Starting… / Stopping…) and the PID.
When the server is stopped, the menu shows Start Server instead.
State is polled every 3 seconds, so the icon stays correct even when you start or stop the server from a terminal.
Show Panel opens a small window with the same actions:
Closing the panel does not quit the app — it stays in the menu bar.
Note the window controls: close and minimize are enabled, while zoom/fullscreen is deliberately greyed out — this is a fixed-size panel, and stretching it full-screen would only add empty space.
This repository ships two independent pieces, and it is worth being clear about which is which:
| Piece | What it is | Installed by | Required? |
|---|---|---|---|
| The app | a macOS menu bar app | ./build.sh | yes — it is the launcher |
| The plugin | a DSH plugin (dsh-menubar-launcher) | dsh plugin add | no — recommended |
The app is the product. The plugin is a small helper that runs inside the server and tells the app the URL to open. The app works without it; see Do I need the plugin? for exactly what changes.
Requires macOS 13+ and the Xcode Command Line Tools (xcode-select --install).
git clone https://github.com/songer522/dsh-launcher.git
cd dsh-launcher
./build.sh
That compiles, bundles, signs, and installs to /Applications. Launch it from
there — it appears in the menu bar, with no Dock icon.
./build.sh --dev # build into ./build without installing
./build.sh --uninstall # remove the installed app
dsh plugin --profile web add https://github.com/songer522/dsh-launcher/releases/latest/download/dsh-menubar-launcher.tgz
Then restart the server — from the app's Restart menu item, or by stopping and starting it however you normally do. A plugin is composed when the server starts, so a server that was already running does not have it, and nothing will appear until it restarts.
Verify it took effect:
cat ~/.config/dsh-launcher/runtime.json
A JSON object means it is working. "No such file or directory" means either the server has not been restarted since installing, or it is not running.
The plugin also appears under Settings → Plugins in the DSH web UI, as
dsh-menubar-launcher with a green active dot.
Use the same profile the app launches. The command above installs into the
webprofile, which is whatdsh weband the app's default command (pnpm dsh web …) both boot. If you changed the app's command in Preferences to use a different profile, pass that profile todsh plugin --profile <name> add …instead, or the server the app starts will not have the plugin.
To remove it: dsh plugin --profile web remove dsh-menubar-launcher.
No. The app has always resolved DSH's per-process token by reading the log of the server it started, and that still works. The plugin matters in the case that mechanism cannot cover — a server the app did not start:
| Situation | Without the plugin | With the plugin |
|---|---|---|
| You start the server from the app | ✅ works (reads its log) | ✅ works |
| The server was started from a terminal | ❌ opens a tab that 401s | ✅ works |
| The server was started before the app | ❌ opens a tab that 401s | ✅ works |
So: install the app alone if you always start the server from the app. Add the
plugin if you also run dsh web from a terminal, or leave a server running
across app restarts.
Both paths are kept deliberately — the plugin is an improvement, not a requirement, and the app never assumes it is there.
On first run the app looks for a DeepSeek Harness checkout in the usual places
(~/Workspace, ~/Projects, ~/Developer, ~/src, ~/code, ~). If your
project lives elsewhere, or you want to launch something entirely different,
open Preferences (⌘,).
Settings are stored as JSON at ~/.config/dsh-launcher/config.json:
{
"repo": "/Users/you/Workspace/deepseek-harness",
"command": "pnpm dsh web --no-open --port {port}",
"port": "3080",
"browser": "Google Chrome",
"logFile": "/tmp/dsh-web.log",
"language": "system"
}
| Field | Meaning |
|---|---|
repo | working directory the command runs in |
command | the launch command; {port} is substituted |
port | the port to watch, and to substitute into the command |
browser | app name to open, or "" for the system default |
logFile | where the server's stdout/stderr is written |
language | interface language: system, en, or zh-Hans |
Because it is just a command in a directory, it happily runs npm run dev,
vite, python -m http.server, or anything else.
The interface is available in English and 简体中文. Choose one under Preferences (⌘,) → Language; it applies immediately, with no relaunch.
The default, System, follows macOS — Chinese when your preferred language is Chinese, English otherwise. The explicit choices exist because running one app in a different language from the rest of the system is common enough among developers to be worth a setting.
The stock command uses --no-open because DSH otherwise opens the URL in the
system default browser. Suppressing that and opening the browser here is
what lets you use Chrome while Safari remains your system default.
The app can manage a server it did not start — but then it has no log to read, and DSH's per-process token lives only in that log. The result was a menu item that opened a tab answering 401.
This repository therefore also ships a Host plugin. It runs inside the
harness, where the port and the token are not parsed but simply known, and
writes them where the app can find them. Install it
with dsh plugin add; installing from source instead of the release tarball
works too, and needs no build step either:
dsh plugin --profile web add github:songer522/dsh-launcher
Once the server restarts, it writes ~/.config/dsh-launcher/runtime.json:
{
"version": 1,
"pid": 29185,
"host": "127.0.0.1",
"port": 3396,
"url": "http://127.0.0.1:3396",
"authenticatedUrl": "http://127.0.0.1:3396/?token=…",
"startedAt": "2026-09-08T21:51:36.643Z"
}
The file is created once the server is listening and removed when it stops,
so its presence is itself a liveness signal. It is written 0600, and the
directory 0700: authenticatedUrl contains a launch token, which is a
credential granting full access to that harness. Treat it like one.
The app prefers this file and falls back to log parsing when it is absent, so
the plugin is optional — without it you get exactly the previous behaviour.
A descriptor is used only when the PID it names is the process currently
listening on the port, so a file left behind by a kill -9 is ignored rather
than used to open a dead tab.
The plugin is not macOS-specific: anything that wants the authenticated URL of a running harness can read the same file.
To move it, restate the row's whole config in your profile's
cordis.patch.yml (a patch replaces a row's config rather than merging into
it) — note that the app looks only at the default path:
- id: dsh-launcher-runtime
config:
path: /somewhere/else/runtime.json
enabled: true
The plugin declares no dependencies at all, so it installs against any harness
version and needs no allowBuilds approval. In a profile without a web server
— headless, say — it simply does nothing and the harness boots normally.
The app is a menu bar utility (LSUIElement), so it has no Dock icon and no
⌘Tab entry. Quit it from the menu bar.
For the optional panel:
| Control | State |
|---|---|
| Close (red) | enabled — hides the panel; app stays in the menu bar |
| Minimize (yellow) | enabled |
| Zoom / fullscreen (green) | disabled — fixed-size panel |
Fullscreen is suppressed both by omitting .resizable from the window's
styleMask and by adding .fullScreenNone to its collectionBehavior, so
⌃⌘F does nothing either.
The server is started detached, so quitting the launcher never stops it. Stopping is always an explicit, confirmed action — the server may be hosting live sessions.
Four details that are easy to get wrong:
1. GUI apps have no shell PATH. A double-clicked app does not read
~/.zshrc and does not inherit a login PATH, so pnpm would simply not be
found. Binaries are resolved explicitly against common install locations, with
a login-shell lookup as a fallback. The spawned server also gets those
directories prepended to its PATH: resolving pnpm alone is not enough,
because it execs node, which would otherwise fail with
env: node: No such file or directory.
2. Authentication tokens must be carried over. DSH mints a per-process launch token and prints the URL with it; the bare origin answers HTTP 401, so the tab would be dead. The app resolves that URL from two sources, in order: the runtime descriptor written by the companion plugin, then the log this run printed. The descriptor is preferred because it is also correct for a server started from a terminal — the case where there is no log to read. Servers that publish neither fall back to the plain URL.
3. Port probing must filter for listeners. This app uses:
lsof -ti tcp:3080 -sTCP:LISTEN
Without -sTCP:LISTEN, lsof also reports every client connected to that
port — your browser, your editor — and acting on those PIDs would terminate
unrelated applications. Only one process can hold LISTEN on a port, so this
targets exactly the server no matter what its PID happens to be.
4. Stopping is graceful. TERM first, escalating to KILL only if the port
is still bound after ~6 seconds.
Everything lives in one file: Sources/DSHLauncher.swift.
swiftc -O Sources/DSHLauncher.swift -o build/DSHLauncher && ./build/DSHLauncher
Nothing to do here if you are just installing — build.sh already gets this
right, and verifies the signature before it finishes. It matters only if you
edit the build script, so the reason the step order cannot be rearranged is
written down.
build.sh signs the bundle last, and that ordering is not cosmetic.
Modifying a bundle after signing — replacing the icon, editing Info.plist —
invalidates the signature, and macOS then refuses to treat the directory as an
application. The visible symptom is that Finder shows a folder icon, which
looks like an icon bug but is really a signature failure:
$ codesign -v "/Applications/DSH Launcher.app"
invalid Info.plist (plist or signature have been modified)
To see the icon macOS actually resolves, bypassing Finder's cache:
osascript -l JavaScript -e 'ObjC.import("AppKit");
var img=$.NSWorkspace.sharedWorkspace.iconForFile("/Applications/DSH Launcher.app");
var rep=$.NSBitmapImageRep.imageRepWithData(img.TIFFRepresentation);
rep.representationUsingTypeProperties($.NSPNGFileType,$()).writeToFileAtomically("/tmp/resolved.png",true);'
open /tmp/resolved.png
If you prefer the terminal, these do the same jobs. Two details matter: the
-sTCP:LISTEN filter, and capturing the tokenized URL instead of opening the
bare origin (which answers 401).
dshweb() {
local port="${DSH_WEB_PORT:-3080}"
local log="${TMPDIR:-/tmp}/dsh-web-${port}.log"
: > "$log" # a stale URL carries a dead token
(cd ~/Workspace/deepseek-harness && pnpm dsh web --no-open --port "$port" > "$log" 2>&1) &
local server=$!
tail -f "$log" & local tailer=$!
while ! nc -z 127.0.0.1 "$port" 2>/dev/null; do
kill -0 "$server" 2>/dev/null || { kill "$tailer" 2>/dev/null; return 1; }
sleep 0.3
done
# DSH prints `dsh web: http://127.0.0.1:PORT/?token=…` — open that, not the
# bare origin. Prefer loopback and exclude brackets: the LAN URL is printed
# on the same line inside parentheses.
local url=""
for _ in {1..40}; do
url=$(grep -aoE "https?://[^[:space:]'\"()]*[?&]token=[^[:space:]'\"()]+" "$log" \
| grep -E "127\.0\.0\.1|localhost" | tail -1)
[ -n "$url" ] && break
sleep 0.25
done
open -a "Google Chrome" "${url:-http://127.0.0.1:$port}"
wait "$server"; kill "$tailer" 2>/dev/null
}
dshkill() { lsof -ti tcp:3080 -sTCP:LISTEN | xargs kill; }
Note that in zsh a background pipeline (cmd | tee log &) sets $! to tee
rather than the server, which breaks the liveness check — hence redirecting to a
log and tailing it separately.
Beware also that lsof -ti tcp:PORT without -sTCP:LISTEN matches clients
connected to the port too, so that widely-shared one-liner can kill your browser.