DSH Pets

Cross-platform desktop pets for DeepSeek Harness.

English | 简体中文

DSH Pets brings your running AI agent sessions onto the desktop through animated characters, event-driven voice lines, and actionable notifications. Keep an eye on parallel tasks, jump to the right session, and know when an agent needs you—without constantly checking the DSH Web interface.

Project status: early development. This README describes the intended product and development milestones. Features listed as planned are not claims that they are already implemented. The project builds on ideas and code from zuodazuoqiang001/dsh-pet, a Windows desktop-pet plugin for DSH.

What it does

The product is organized around four focused modules:

Module	Planned capabilities
Session Management	Show active top-level DSH sessions, quickly switch to a selected session, and notify on task completion, failure, or approval requests. Keep missed notifications accessible.
Character System	Display Spine characters or sprite-sheet pets, associate characters with model identities, and map agent states to expressions and motions.
Voice System	Play pre-recorded voice lines for events, with character-specific voice packs, volume/mute controls, cooldowns, and optional lip sync.
Desktop Interaction	Transparent floating window, drag/position persistence, system tray, click-through behavior, do-not-disturb mode, and basic performance settings.

Two non-negotiable capabilities:

1. Switch between running sessions quickly from the desktop pet's session list or bubbles.
2. Receive reliable task-completion alerts, including an actionable path back to the corresponding session.

Character animation and voice make these workflows more expressive; they must never prevent session controls and notifications from working.

How it should feel

• Working: a character reacts to an active agent; session bubbles show what is still running.
• Needs attention: the character signals an approval request and offers a direct session shortcut.
• Completed: an animation and optional recorded line announce the result; the notification remains available until reviewed.
• Idle: the character returns to subtle idle motions without interrupting desktop work.
• Multiple agents: notifications are queued or coalesced instead of playing several voice lines simultaneously.

Characters may be mapped to model families (for example, DeepSeek, Claude, or GPT), with manual overrides. A session remains identified by its session ID even if the model changes.

Planned architecture

DeepSeek Harness (DSH Web / Cordis plugin)
  ├─ Session and agent status
  ├─ Task completion / failure / approval events
  └─ Session focus and navigation
                 │
                 │ Local, restricted communication
                 ▼
Electron desktop companion (main process)
  ├─ Connection / notification / session controllers
  ├─ Window, tray, platform integration
  └─ React + TypeScript UI
       ├─ Session bubbles and notification history
       ├─ Spine renderer (primary character format)
       ├─ Static-image fallback (no GPU / reduced mode)
       └─ Pre-recorded voice playback + optional lip sync

Target platforms: Windows, Linux, and macOS. Initial desktop verification is planned for Ubuntu 24.04 Desktop with DSH Web, with Windows and macOS compatibility tests following. Linux X11/XWayland and native Wayland have different restrictions around global window positioning, always-on-top behavior, and focus; support will be documented based on real testing rather than assumed.

Character assets

Character packs are self-contained directories with a single contract file. The bundled default pack ships inside the package; every other pack is downloaded on demand into the user's data directory, which takes precedence over the bundled copy.

assets/characters/                 # bundled, read-only
  index.json                       # downloadable-pack index (version, sha256, url)
  deepseek/                        # the only pack shipped with the package
    manifest.json
    LICENSE
    preview.webp
    spine/                         # Spine skeleton, atlas and textures
    voice/
      index.json                   # voice index: every event and line the pack can speak
      <event>/<id>.ogg             # one file per line, e.g. task_completed/task_completed_01.ogg

~/.dsh/pets/characters/<id>/       # downloaded, writable, overrides the bundled copy

manifest.json is the contract, so the runtime never guesses file names. It declares the Spine entry plus scale and anchor, the agent-state → animation mapping (idle, working, attention, done, failed), the location of the voice index (voice.index), and a static-image fallback for machines without GPU acceleration. The event set is defined by the voice index, not enumerated in the manifest: the bundled pack currently ships 48 lines across 34 events, each line addressed as voice/<event>/<id>.ogg. A voice pack carries no version of its own — the pack's version in manifest.json covers art, animation and audio together. A pack may ship no voice index at all, and every event then stays silent.

This layout is the agreed target: the bundled pack already ships its assets this way, but runtime voice playback is not implemented yet. Voice lines are recorded or generated ahead of time and shipped inside a character pack. There is no runtime text-to-speech generation requirement, no mandatory TTS API, and no need to send session text to a speech provider.

Tools for producing illustrations, skeleton animation, or audio may be used offline during asset creation; they are not part of the DSH Pets runtime.

Roadmap

v0.1 — Usable desktop companion

• DSH plugin connection and reliable per-session state tracking
• Active-session bubbles/list and one-click session navigation
• Completion, failure, and approval alerts with deduplication
• Missed/unread notifications and safe reconnection behavior
• Cross-platform desktop window and tray foundation
• Spine character rendering with static-image fallback
• Pre-recorded voice playback, mute, and event cooldown
• Dragging, remembered position, and basic do-not-disturb controls
• Ubuntu 24.04 end-to-end verification

Later improvements

• Model-to-character mapping, character-pack management UI, and on-demand pack download
• Better mouth-motion synchronization and natural idle interactions
• Edge docking, auto-hide, and configurable mouse pass-through
• Power-saving / reduced-frame-rate mode
• Wider Windows, macOS, X11, and Wayland compatibility coverage

The roadmap is indicative and may change as implementation and compatibility testing progress.

Installation

No stable cross-platform release is documented yet. Once an installable version is available, installation steps and supported DSH versions will be published here. Please do not assume the original Windows-only dsh-pet installation instructions apply to this project.

Current plugin shape (development)

The repository is already installable as a Host-only Cordis bundle: package.json declares dsh.bundle.patch, cordis.patch.yml activates the entry, and index.js registers every bundled skills/<name>/SKILL.md as an agent skill. As a result the character-pipeline skill three-view-parts appears in the skill catalog without being copied into .agents/skills.

# Link this checkout into a profile (example: the web profile)
dsh plugin --profile web add /path/to/dsh-pets

# Restart Harness afterwards so the bundle is activated; the skill then appears
# in the session skill catalog and can be loaded by name.
# Uninstall
dsh plugin --profile web remove dsh-pets

At this stage the bundle only registers skills. The pet window, session tracking, voice playback, and tray integration remain planned work; see the roadmap above.

Reliability, privacy, and resource usage

Design priorities:

• Prefer explicit task lifecycle signals; losing connectivity must not be mistaken for successful completion.
• Deduplicate completion events, retain unread notices, and restore the visible state after reconnection when supported by DSH.
• Keep controls usable when the character renderer, audio, or GPU acceleration is unavailable.
• Keep communication local by default and restrict exposed control endpoints; remote-access configurations must be secured separately.
• Do not read task contents aloud by default. Recorded voice lines communicate predefined status messages, not arbitrary code, secrets, or chat content.
• Provide mute, do-not-disturb, and lower-resource options for long-running desktop use.

These are engineering goals, not a security audit or a claim of completed functionality.

Development and contributions

The project is in an early stage. Issues, platform-specific bug reports, and reproducible test cases are welcome. Before proposing new features, please prioritize the two core workflows: session switching and reliable completion notifications.

Attribution and licensing

This project uses split licensing: source code is MIT, character art is CC BY-NC-SA 4.0. The authoritative text is the root LICENSE.

Project code: MIT

DSH Pets is intended to evolve from zuodazuoqiang001/dsh-pet (MIT). Source code, scripts and docs are MIT, and reused upstream code keeps its original copyright and license notices. The MIT grant does not extend to assets/characters/.

Character packs: CC BY-NC-SA 4.0, non-commercial

The bundled deepseek pack is built on community fan artwork and is distributed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0), following the original author's copyright statement. Three rules apply:

1. The attribution chain must stay complete. The whale-girl prototype is by 上善无形 / 上善, the DeepSeek personification redesign is by ZipZipPipe (author page), and this project contributes the derivative production and packaging. All three must be credited; omitting any link breaks the license.
2. Free distribution is not commercial permission. Publishing free-of-charge on GitHub Releases or npm satisfies the non-commercial requirement, but it neither grants nor transfers any commercial right. Nobody may put a pack or its derivatives into commercial products, paid services or for-profit distribution on that basis.
3. We cannot license rights we do not hold. Every character, texture and audio asset needs its own verified upstream authorization; anything unverified is excluded, and the reasons are listed in ATTRIBUTION.md. Third-party assets keep their own licenses — this project grants nothing on their behalf.

• Reuse requires: keep attribution, indicate your changes, non-commercial use only, and release derivative contributions under the same CC BY-NC-SA 4.0.
• Every pack ships its own LICENSE and ATTRIBUTION.md beside its assets — see assets/characters/deepseek/LICENSE and ATTRIBUTION.md for the full provenance chain and the assets deliberately not included.
• Takedown: if a rights holder objects to any included asset, open an issue with the file path and a verifiable source; the asset is removed after verification. CC licenses are irrevocable, so this commits us to stopping distribution, not to amending the license.
• Character packs are themed after model families but are not official brand material.

Trademarks

Names and marks such as DeepSeek, Claude, GPT, Kimi, and Qwen belong to their respective owners. Nothing in this project implies affiliation with or endorsement by any of them.

Spine runtime

Spine runtimes and exported animation data are subject to Esoteric Software's commercial licensing terms; confirm the applicable terms before shipping. Other third-party SDKs and assets keep their own licenses.

---

DSH Pets — A small, always-available desktop entry point for your AI agent sessions.