dsh-pet-indesktop: a PySide6 desktop pet that runs outside the DSH runtime

What dsh-pet-indesktop solves, and who it is for

The upstream project PC2005-cloud/dsh-pet was tied to the DSH runtime. dsh-pet-indesktop removes that coupling: the README describes it as an independent desktop pet built on Python and PySide6, with a transparent frameless window, always-on-top behaviour, dragging, character switching, animation playback, a system tray icon and optional AI chat. The stated goal is to let the same character run on Windows, Linux and macOS.

The audience is narrow but clear. It is for people who already know the DSH pet character and want it on a normal desktop, and for Python developers who want a working reference for a Qt overlay window that plays video clips. It is not a general-purpose animation framework. The repository layout confirms this: pet/ holds the application, assets/ holds the animation material, integrations/ holds the DSH bridge and Claude hooks installer, and packaging/ holds the build scripts.

The README also carries a long development-constraints section drawn from what it calls a data-driven performance and structure pass. That section is unusual for a hobby-scale desktop toy: architecture tests in tests/test_architecture.py fail CI if pure-logic modules such as collision.py, physics.py or collision_codec.py import PySide6, and window.py has a hard line budget of 4429 lines. Whether you agree with that discipline, it tells you the maintainer expects contributors to read AGENTS.md before sending a patch.

How the pet window, the decode fanout and the config slots fit together

The mechanism visible in the README and the file list is a single Qt process that owns one or more frameless windows, plus a shared video decode chain. The README states that multiple pets of the same character in one process keep a single ffmpeg decode chain and fan frames out to the other windows, which subscribe to it. That is why the repository contains decode_fanout.py and why the architecture rules forbid it from depending back on window.py. Window hooks are injected rather than imported.

Configuration is split by scope, and this is the part most likely to surprise a new user. Per-window items such as appearance, position and chat history are stored in config-slot-N.json. Process-level items such as the tray, the shared decoder, agent linkage and to-do reminders are read from the main pet's config.json, and the README states that changes made in a non-main window do not take effect. New sub-pets are seeded from the main configuration only when their slot has no saved file; an existing user save is always preserved.

Interactions are implemented as separate systems rather than one monolith. The README names edge probing, a golden-spin animation, a knock-away easter egg, file-drop eating, a to-do reminder panel with advance notice and a ten-minute grace period, and a power-saving mode that drops to half frame rate after 30 seconds idle. The release notes for v4.2.0 report a measured 54.6 percent reduction in decode CPU in that idle state. That number comes from the project's own release notes, not from an independent test.

Installing dsh-pet-indesktop and running the first pet

The README offers three distribution forms: an Inno Setup installer (.exe), a portable zip, and a one-directory PyInstaller build. The README states that neither the installer nor the portable version unpacks at runtime or writes temporary caches, which is why startup is described as fast and uninstall as clean. Downloads are on the GitHub Releases page.

If you want to run from source instead, install the runtime requirements and start the entry point. The requirements file lists PySide6, imageio-ffmpeg, Pillow, keyring, certifi, tzdata and edge-tts, with pycaw added only on Windows.

pip install -r requirements.txt
python -m pet

On Windows the repository also provides a run.bat launcher at the top level. The README does not document a command-line flag set for the entry point, so configuration is done through the settings dialog rather than through arguments.

After the pet appears, the settings dialog is where the per-window and process-level options live. The README describes the v4.2.0 settings dialog as organised into seven capability areas, with a right-click menu editor that lets you set visibility, submenus, separators, aliases and icon overrides, with a live preview on the right. A damaged menu configuration falls back to a safe menu automatically.

To spawn a second pet, enable multi-instance under Settings, General, then use the spawn entry in the right-click menu. The README states that the new pet gets its own slot, configuration, session and asset library, and that quitting a sub-pet exits it without deleting its settings, session or to-do data. If you are upgrading from an older one-file build, the README has a separate section on clearing the old onefile cache; newer releases do not need it.

Where dsh-pet-indesktop breaks or is the wrong choice

The most concrete limitation is platform asymmetry in the feature set. The README labels proactive screen awareness as Windows and Chat-edition only, and the requirements file pulls pycaw only on Windows. If you are on Linux or macOS and that feature is what you came for, the project does not offer it there.

The second limitation is documentation language and coverage. The README, the release notes and the development rules are written in Chinese. The English-speaking reader gets a partial picture at best, and there is no separate English manual in the repository listing. The README also does not document rollback, so if a new release misbehaves on your machine, there is no described procedure for returning to an earlier version beyond downloading the older release asset yourself.

The third is the contribution model. The architecture tests freeze internals: PetWindow private attributes are only allowed to be touched by window.py itself and collision_client.py, and new top-level config keys must be registered in three places at once (the defaults dict, the reload whitelist, and a schema snapshot test). That keeps the codebase coherent, but it means the project is not a good base for a quick fork that bolts on a new panel. If you want to extend the pet without reading AGENTS.md and docs/WINDOW_PY_SPLIT_GUIDE.md first, expect CI to reject the change.

Finally, the packaging path is not trivial to reproduce. The README mentions three build scripts and a --collect-all edge_tts requirement because edge-tts resolves its version through importlib.metadata and uses dynamic submodule imports that PyInstaller's static analysis misses. Building your own binary means working through packaging/ rather than running a single documented command.

How this differs from a screenmate-style pet or a full widget toolkit

The obvious comparison is a desktop mascot built on a general widget toolkit, such as a Shimeji-style Java pet or a GNOME shell extension. Those usually rely on the host platform's window manager or a shell runtime: Shimeji-style pets are Java processes that draw their own transparent window, while shell extensions only exist inside that shell. dsh-pet-indesktop takes a third route. It uses Qt for the window and ffmpeg, via imageio-ffmpeg, for the animation decoding, so the same code path runs on all three desktop platforms and the animation format is video rather than a sprite sheet.

That choice has a cost. A Qt overlay with video decoding is heavier than a sprite-based pet that blits PNG frames, and the project's own release notes spend a lot of space on memory stability and idle CPU precisely because of that weight. The compensating benefit is that character animation is authored as ordinary video clips, and the README states that the animation asset count grew from 97 to 106 in v4.2.0 with DLC character swapping.

A second difference is the agent bridge. The integrations/ directory and the README describe a DSH bridge plugin and a Claude hooks installer, so the pet can react to an AI agent's state: thinking, working with a tool name, attention, error, plus approval and question bubbles. Most desktop pets have no such hook. If you do not run an agent, that whole layer is inert, and the README notes that the bridge plugin was reworked to have zero external dependencies.

Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-16, one day before this writing. Releases are frequent: v4.0.5 on 2026-08-30, v4.1.0 on 2026-09-02 and v4.2.0 on 2026-09-10. The README additionally describes an unreleased main branch labelled as a v4.2.1 candidate, with a list of merged pull requests. Treat the release cadence as high and the stability expectation as correspondingly modest.

The upgrade cost is mostly in configuration, not in the binary. The README states that new top-level config keys must be registered in the defaults dict, the reload whitelist and the schema snapshot test, and that special keys such as version, proactive_screen, agent_link and chat follow dedicated migration paths. For a user, the practical consequence is that settings survive upgrades, and that a corrupted menu configuration falls back to a safe menu rather than leaving you with an unusable right-click menu. The README does not describe a downgrade path.

The licence is MIT, and the repository carries a THIRD_PARTY_NOTICES.md file alongside LICENSE. MIT is permissive, but the animation assets and the DSH-derived material are a separate question from the code licence; the README has a section on the project's origin and asset provenance, and that is the section to read if you plan to redistribute the character rather than just run it. Nothing here is legal advice, and the notices file is the authoritative place to check what the project itself claims about third-party components.

Editorial conclusion

Adopt it if you want a transparent, always-on-top pet on Windows, macOS or Linux and you are comfortable with a project whose main development thread is currently in Chinese. Do not adopt it if you need a documented plugin API, stable third-party extensions, or a packaged build you can reproduce yourself without following the Inno Setup and PyInstaller scripts in packaging/. Before installing, read docs/RELEASE-v4.2.0.md and the known-limitations section of the README, then verify that the release asset for your platform matches the onedir layout the README describes.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MerZlin/dsh-pet-indesktop on GitHub
4. README
5. Releases