dsh-desk-pet DSH plugin

DSH Desk Pet is a transparent, frameless system window that displays a cute whale (or other skins) on your desktop. It automatically changes expressions based on the state of your local DSH agent, such as idle, working, waiting, error, happy, or sleeping. It can be dragged, clicked, and skinned via right-click menu.

ui-productivity

How to install the dsh-desk-pet DSH plugin

dsh plugin --profile web add github:anneheartrecord/dsh-desk-pet#main

Copying does not run this command. Review the repository and version before installing the dsh-desk-pet DSH plugin.

dsh-desk-pet DSH plugin data source

dsh-desk-pet DSH plugin snapshot date: Aug 16, 2026

discovered

What the dsh-desk-pet DSH plugin can do

Automatically reflects DSH agent status (idle, working, waiting, error, happy, sleeping) with corresponding expressions.
Drag by clicking and holding the body; click to make it jump or wake up from sleeping.
Four skins: whale (default), threadcore, nautilus, jellyfish, switchable via right-click menu or number keys 1-4.
Closes via Esc or q key, or through the right-click menu.
Can be set to transparent mode with `--transparent` flag if Tk supports it.
Uses macOS AppKit (via ctypes) to stay above full-screen apps when possible, falls back to normal pinning.

Where the dsh-desk-pet DSH plugin fits

Monitor DSH agent status at a glance without opening the DSH web interface.
Add a cute desktop companion while working, with visual feedback on agent activity.
Quickly see if DSH is waiting for user input or has encountered an error.
Use as a visual indicator during long-running tasks, such as batch processing or data analysis.
Enjoy as a standalone desktop pet (without DSH) by running `./bin/dsh-desk-pet` from the cloned repo.

Who the dsh-desk-pet DSH plugin is for

DSH users who want a visual status indicator for their agent.
macOS users who enjoy desktop pets and want a lightweight, customizable pet.

dsh-desk-pet DSH plugin limitations

Full-screen apps may obscure the pet on systems where the AppKit trick doesn't work; it will fall back to normal pinning.
Transparent mode is disabled by default due to Tk compatibility issues on macOS (Tk 8.5.9); may not work on all systems.
Only tested on macOS; Windows and Linux may not be fully supported, especially the AppKit-based full-screen workaround.
As a DSH plugin, it requires DSH to be installed and running for status updates; standalone mode requires manual cloning of the repository.

dsh-desk-pet DSH plugin: from the repository README

Quoted from the anneheartrecord/dsh-desk-pet README, the upstream source of the dsh-desk-pet DSH plugin. Copyright remains with the original authors.

盖在所有窗口之上的桌面宠物，跟着本地 DSH 的状态自己变表情。默认鲸鱼，四套皮肤。不是网页里的挂件——是一个无边框透明的系统窗口。DSH 页面里那只是它的镜像。 [English](README_EN.md) ## 安装已有 DSH，一条命令： ```bash dsh plugin --profile web add github:anneheartrecord/dsh-desk-pet#main ``` macOS 用系统自带的 `/usr/bin/python3`，不需要装任何依赖。 ## 启动 ```bash dsh web ``` 宠物会自己浮在桌面上。DSH 页面右下角还有一只同步的镜像。不要 DSH、只开宠物：克隆后执行 `./bin/dsh-desk-pet`。 ## 已知限制 **全屏 app。** Tk 自己只有布尔的「置顶」，跨不过 macOS 全屏应用独占的 Space。所以本插件绕过 Tk，用标准库 `ctypes` 直接调 AppKit（`src/dsh_desk_pet/macwindow.py`）：把 NSWindow 提到辅助功能层级，并设成可加入所有 Space——和 Electron 桌宠同一套机制，只是不需要装任何依赖。调不通的机器会自动退回普通置顶，那时全屏会盖住它。 **为什么有个浅色底板？** 默认不透明是实测后的选择。macOS 自带的 Tk 8.5.9 上，`-transparent` 会把**整个窗体**合成为空——Tk 报告窗口已映射、可见、坐标正确、精灵在画布上，截图里却是一片空桌面。镂空更好看，但看不见的宠物不是宠物。你的 Tk 支持的话可以开回来： ```bash ./bin/dsh-desk-pet --transparent ``` ## 使用 - **拖**：按住身体任意处。 - **点一下**：它会跳一下；在打盹的话会被叫醒。 - **换肤**：右键（或 Control+点击）出菜单，也可以按 `1`–`4`。换肤不改状态。 - **关掉**：`Esc` 或 `q`，或右键菜单里选退出。 ## 状态跟着本地 DSH 自动变，不用管。 | 状态 | 什么时候 | | --- | --- | | 空闲 | 没事干，会呼吸、偶尔眨眼 | | 干活 | DSH 正在跑 | | 等你 | 卡在确认、授权、要你输入 | | 报错 | 跑挂了 | | 开心 | 刚跑完一轮，几秒后自己回到空闲 | | 睡着 | agent 没事干**且**你的鼠标也不动了才打盹；一有动静或者你戳它就醒 | ## 皮肤 | 圆点 | id | | --- | --- | | 蓝 | `whale`（默认） | | 橙 | `threadcore` | | 棕 | `nauti

Read the full READMERepository license: MIT

dsh-desk-pet DSH plugin questions

How do I install DSH Desk Pet?

Make sure you have DSH installed. Then run `dsh plugin --profile web add github:anneheartrecord/dsh-desk-pet#main`. After that, start `dsh web` and the pet will appear on your desktop.

How do I change the skin of the pet?

Right-click (or Control+click) on the pet to open the context menu, then select the desired skin. You can also press the number keys 1 through 4 to switch between the four skins: whale, threadcore, nautilus, and jellyfish.

Why is the pet not transparent? I see a background color.

The transparent mode is disabled by default because macOS's built-in Tk 8.5.9 has a bug where `-transparent` makes the entire window invisible. If your Tk version supports it, you can enable transparency by running `./bin/dsh-desk-pet --transparent` in standalone mode. As a plugin, transparency is not supported currently.

Can I use DSH Desk Pet without DSH?

Yes, you can run it standalone. Clone the repository and execute `./bin/dsh-desk-pet` from the project root. In standalone mode, the pet will not have status updates from DSH, but you can still enjoy the pet as a desktop decoration.

Does it work on Windows or Linux?

The plugin is primarily tested on macOS. It uses macOS-specific APIs (AppKit via ctypes) for the full-screen workaround. On Windows or Linux, it may still work but with limited functionality: the full-screen avoidance may not work, and transparency may behave differently. We recommend using it on macOS for the best experience.