dsh-desktop-pet

One-Line Description

DSH Whale-Girl pet companion for Linux/Windows desktop: a transparent, always-on-top, frameless floating pet window that connects via local HTTP reverse connection to the running DSH Web service, automatically reflecting session activities (thinking/tool calls/waiting for approval/task completed), and mutually exclusive with the web-side pet (automatically hides the web-side when online).

Note: The command dsh plugin ... add only registers this plugin in the DSH CLI's bundle list and does not automatically start the desktop application; the actual desktop binary needs to be manually downloaded from GitHub Releases.

Core Features

• Places a transparent always-on-top frameless floating pet window in the bottom-right corner of the desktop, with no taskbar icon, can be obscured by other windows but won't disappear
• Automatically switches animations following DSH session activities: thinking, using tools, waiting for approval, task completed, round celebration, error, resting
• Left-click to feed, right-click to play, interacts with DSH /whale-girl/interact interface; after triggering, plays short bubble feedback
• When idle, walks horizontally along the bottom of the screen (window actually moves), bounces and turns when hitting workspace edges, speed and interval adjustable
• The bubble area at the top of the window displays multiple session statuses simultaneously (thinking/waiting for approval/completed), turns red as a reminder when any session is waiting for approval
• After dragging, window position is automatically saved locally, persists after restart; also notifies web-side Whale-Girl via heartbeat to automatically hide

Technical Implementation

• Language: JavaScript / CommonJS (Electron version + shared layer) + Rust (Tauri version) + Native HTML/CSS/JS (renderer, no framework)
• Key Dependencies: tauri 2 (with tray-icon feature), reqwest (pure HTTP, no TLS, loopback requests), tokio (async runtime), tauri-plugin-opener (open web-side from tray)
• Architecture: Dual implementation—Electron (src/main.cjs) and Tauri (src-tauri/src/lib.rs) share DSH URL validation and state selection logic from src/shared.cjs; DSH bundle side only registers an inert placeholder (apply() is an empty function), real application connects via HTTP reverse connection to running DSH Web service
• Entry Files: src/main.cjs (Electron entry) / src-tauri/src/lib.rs::run (Tauri entry); renderer src/renderer/renderer.js

Use Cases

Linux or Windows users who want to "take out" DSH's Whale-Girl pet from the browser, able to see session progress without switching windows (thinking/using tools/waiting for approval). Particularly suitable for users with multiple sessions open—the desktop companion's multi-session bubbles at the top let you instantly see which sessions are waiting for your approval. If you're already viewing the Whale-Girl in the browser, this plugin is not for you.

Prerequisites and Compatibility

Installation

dsh plugin --profile web add github:xiaoshihou514/dsh-desktop-pet

After installation, you need to go to GitHub Releases to download the desktop binary and manually start it. This command only registers the bundle and does not automatically start the desktop application.

Configuration

This plugin requires no additional configuration—the DSH bundle side dsh-plugin.mjs has an empty apply() function, cordis.patch.yml only registers an empty plugin slot, and does not expose any Schema configuration items to DSH.

Runtime experience parameters for the desktop application (pet size, opacity, bubble duration, walk toggle and speed, etc.) are managed uniformly by the upstream whale-girl plugin's /whale-girl/config endpoint. Please adjust them in the whale-girl plugin's settings page.

FAQ

Q: Will I see the pet on the desktop immediately after executing the installation command?

A: No. This command only registers this plugin in the DSH CLI's bundle list. The actual desktop application needs to be downloaded from the repository's GitHub Releases (AppImage/deb/RPM/NSIS/portable binary) and manually started.

Q: Must DSH be running to use it?

A: Yes. The desktop side connects via local HTTP to the running DSH Web service (default http://127.0.0.1:3080). When DSH is not started, the window will display "Please start DSH Web service".

Q: Can it connect to a remote DSH?

A: Yes, you can specify the address via --dsh-url startup parameter or DSH_URL environment variable, but the address must point to localhost (127.0.0.1/localhost/::1). Non-loopback hosts will be rejected by shared.cjs's normalizeDshUrl.

Q: Will opening the web-side pet simultaneously cause conflicts?

A: No. The desktop side sends a presence heartbeat every 15 seconds. When the desktop side is online, the web-side Whale-Girl automatically hides; after desktop side exits or crashes, the 45-second TTL expires and the web-side automatically restores.

Q: Can I drag the pet or let it walk under Wayland?

A: No. Under Wayland, window movement is handled by the compositor, programmatic set_position is not available. The desktop side will automatically disable drag and walk features. It only works under X11/XWayland.

Q: Why can't I close the window with Alt+F4/close button?

A: It's by design. Ctrl+W, Alt+F4, and window manager close requests are all intercepted. You can only exit from the system tray menu "Quit" or the × button inside the window to avoid accidental closing.

Q: Can macOS use it?

A: The macOS branch exists in the source code but is not enabled. package.json has no macOS build configuration, CI release.yml has no macOS job, and README does not declare macOS packages.

Difficulty Level

Advanced — The installation command itself is just one line, but the actual usable desktop application requires manually downloading binaries from GitHub Releases, ensuring the upstream whale-girl plugin is installed, and DSH Web service running on port 3080; all interactions (feeding, walking, switching session bubbles) are clickable on the UI, no programming required.

Known Issues and Limitations

• macOS build target not configured: The darwin branch (ozone selection, setAlwaysOnTop) exists in the source code, but package.json has no macOS build configuration, CI release.yml has no macOS job, and README does not declare macOS packages
• Drag/walk disabled under Wayland: canProgrammaticallyMove returns false under Wayland sessions. Drag (pet:drag-move) and walk (pet:walk-move) directly short-circuit return moved: false, only available under X11/XWayland
• Forced loopback: DSH_URL must point to localhost (normalizeDshUrl rejects non-127.0.0.1/localhost/::1 hosts), remote DSH cannot connect directly
• Forced software compositing on Linux: app.disableHardwareAcceleration is unconditionally enabled on Linux to avoid transparent window instability issues with Mesa/NVIDIA + certain compositors; GUI performance depends on CPU
• macOS close interception is hardcoded: on_window_event always intercepts CloseRequested (unless explicitly set with quitting flag). Tray menu is the only normal exit channel, users accustomed to Alt+F4 may find it awkward
• High barrier for cross-platform Windows toolchain: Cross-compiling Windows on Linux hosts in CI requires cargo-xwin + windres + mingw gcc + nsis + libayatana-appindicator; release.yml uses ~80 lines specifically for this configuration

啊哈哈哈，大肥鱼来喽！

感谢 @vlln 的付出！这是大肥鱼的 Linux / Windows 桌面版适配~

npm i -g @deepseek-ai/dsh
dsh plugin --profile web add "github:vlln/whale-girl#main"

# 随后在发行版页面下载 AppImage、RPM 或 Windows 安装包：
# https://github.com/xiaoshihou514/dsh-desktop-pet/releases

可爱的同时可以显示干活进度、是否需要审批等等

点个星标吧~这对我真的很重要

许可：MIT

也看看我其他的插件吧～

• dsh-weixin
• dsh-vision
• dsh-tui