dsh-launchpad

English | 中文

One-window launcher for DeepSeek Harness (dsh) on macOS and Linux — with API balance tracking, spend alerts, and a custom chat background.

DeepSeek Harness is excellent, but day to day I kept hitting three small annoyances: remembering the start command, having no idea how fast I was burning credit, and looking at a plain UI. This wraps all three into one window.

Not affiliated with DeepSeek. This is a standalone companion tool that drives the official dsh CLI — it does not fork, vendor, or modify the upstream project.

Screenshots

One window controls everything	Custom chat background

Why

One click, nothing to remember. Open it and it starts the service, waits until it is actually ready, and jumps straight to the Web UI. No command to memorize, no port to type, no browser tab to open by hand.

• Never re-enter your API key. You paste it once in the Web UI; dsh stores it, and everything here — including the balance checks — reuses that same key. This project never asks for it.
• Always know what you're spending. Balance shows up the moment you launch, and a background check warns you as you burn through credit.
• Clean stop. Close the window and the service is gone — no leftover process quietly holding the port.

What it does

• One window, one service. Launch it; the window shows your balance, starts the service, opens your browser, and streams the log. Closing the window (or Control+C) stops the service — no orphan process left holding the port.
• Balance on startup. See the current balance and what this "round" has cost before you start working.
• Spend alerts. A background check runs every 10 minutes. Each time you spend a set amount (default 5), you get a desktop notification telling you how long that amount lasted. Below a set balance (default 10), it warns you to top up.
• Custom background. Drop in any image and it becomes the chat background, with automatic light/dark handling so text stays readable.

Balance tracking works even when the service is stopped, since it polls the DeepSeek API directly.

Where things live

This tool changes nothing about how dsh stores your data — sessions and credentials stay exactly where dsh puts them.

Path	What	Owned by
~/.dsh/sessions/	Chat history — one append-only log per session, written as you go	dsh
~/.dsh/.credentials.yaml	Your API key, write-only	dsh
~/.dsh/settings.yaml	Model and theme preference	dsh
~/.dsh-launchpad/	This tool: config, usage snapshot, theme, logs	this project

Because history is flushed to disk continuously, stopping the service — or a crash, or a reboot — never loses past conversations. Only work still in flight is interrupted.

Requirements

• macOS or Linux
• Node.js — the only hard dependency; npx fetches dsh itself

	macOS	Linux
Notifications	osascript (built in)	notify-send (libnotify)
Scheduling	launchd (built in)	systemd user timer, falls back to cron
Port check	lsof (built in)	lsof or ss
Image resize	sips (built in)	ImageMagick (optional — skipped if absent)

No Homebrew packages, no jq, no Python.

Install

git clone https://github.com/jovequli/dsh-launchpad.git
cd dsh-launchpad
./install.sh                        # or: ./install.sh ~/Pictures/your-wallpaper.jpg

Installs to ~/.dsh-launchpad/, adds a launcher, and registers the background monitor.

Then:

1. Start it (see below).
2. In the Web UI, go to Settings → Models and paste your DeepSeek API key. It is stored write-only by dsh in ~/.dsh/.credentials.yaml — this project never asks for or stores your key separately.
3. Pick a workspace and start working.

Usage

Action	macOS	Linux
Start	Double-click DeepSeek.command on the Desktop	Launch DeepSeek Harness from your app menu, or run bash ~/.dsh-launchpad/console.sh
Stop	Close the window, or Control+C	Same

Window open = service running. Window closed = service stopped. If an old service is already running, the launcher takes it over so there is never more than one.

Stopping the service does not affect your chat history — sessions are written to disk continuously under ~/.dsh/sessions/.

macOS: the first double-click may say "cannot be opened because it is from an unidentified developer." Right-click the file → Open → Open. Only needed once.

Linux: some desktops require you to mark the .desktop file as trusted before double-clicking (right-click → Allow Launching).

Configuration

Edit ~/.dsh-launchpad/config.sh (takes effect on next start, no reinstall needed):

PORT=3080              # Web UI port
WORKDIR="$HOME"        # directory dsh starts in
ALERT_STEP=5           # notify after spending this much
ALERT_LOW=10           # notify when balance drops below this
MONITOR_INTERVAL=600   # background check interval, seconds

Changing MONITOR_INTERVAL requires re-running ./install.sh to regenerate the scheduled job.

Custom background

Put any image at ~/.dsh-launchpad/theme/bg.jpg, then run:

~/.dsh-launchpad/apply-theme.sh     # then refresh the browser

Tune the look in ~/.dsh-launchpad/theme/custom.css:

--bg-fade-dark: 0.62;    /* lower = image more vivid, higher = text clearer */
--bg-panel-alpha: 0.80;  /* set to 1 for fully solid message panels */
--bg-fade-light: 0.82;   /* light theme scrim */

Revert to the stock look with ~/.dsh-launchpad/apply-theme.sh --remove.

How it works: dsh serves a static frontend, so this copies your CSS and image into that directory and adds one <link> to index.html. Two details make it survive real use:

• It targets only stable selectors (body and the official --dsw-alias-* design tokens). Compiled class names like _boot_9gj4p_6 carry a content hash that changes on every release, so styling against them would break constantly.
• npx replaces the package folder whenever dsh updates, which would wipe the customization — so the launcher re-applies it on every start, idempotently.

Uninstall

./uninstall.sh

Removes the launcher, the scheduled monitor, the theme, and ~/.dsh-launchpad/. It does not touch ~/.dsh/, where your sessions and API key live.

Notes

• DeepSeek Harness is in developer preview and changes fast. If a future release restructures the frontend, the background injection may need updating; everything else only depends on the public CLI.
• The DeepSeek API exposes current balance only — there is no historical usage endpoint. The "how long did that amount last" figure is computed from local snapshots. For a token-level breakdown, see platform.deepseek.com/usage.
• Windows is not supported. The scripts rely on POSIX shell plus platform notification/scheduling tools; a Windows port would need a PowerShell rewrite. WSL should work like Linux.
• Console output is in Chinese; the strings are plain text near the top of each script if you want to change them.

License

MIT