Introduction
In the era of autonomous coding agents and deep foundation models, the collaborative dynamic between software engineers and AI assistants has evolved from atomic prompt-and-response exchanges into long-horizon, autonomous engineering tasks. During prolonged multi-file refactoring, contextual codebase indexing, and multi-step tool execution, developers often find themselves waiting on silent command-line streams or sterile progress indicators, lacking an intuitive and engaging window into runtime execution.
Engineered by open-source development team PC2005-cloud, dsh-pet bridges this gap as an interactive desktop pet companion built specifically for DeepSeek Harness (dsh). Operating as a lightweight, floating transparent window on the user's desktop, dsh-pet transforms cold terminal execution into a lively visual experience. Far from being a static desktop toy, dsh-pet integrates natively with the Cordis microkernel event bus, establishing bidirectional synchronization with the AI agent lifecycle. When large language models enter intensive chain-of-thought reasoning, invoke sandbox utilities, modify codebases, or encounter runtime exceptions, the pet dynamically transitions between expressive animations, situational gestures, and contextual speech bubbles.
Core Features
Real-Time AI Agent Lifecycle Synchronization & Event Reflection
dsh-pet hooks natively into the DeepSeek Harness runtime event emitter, mapping granular agent state transitions to expressive character behaviors:
- During extended reasoning and thinking phases, the pet enters a focused contemplative posture or displays an animated ticking clock;
- When the agent invokes bash sandboxes, file readers, or compiler tools, the pet brandishes miniature tools or flips through code references;
- Upon encountering network timeouts or execution errors, the pet expresses humorous distress alongside actionable diagnostic hints;
- When tasks conclude successfully and pull requests are pushed, the pet leaps and celebrates with confetti animations.
Ultra-Lightweight Transparent Animation Engine
Constructed around hardware-accelerated transparent rendering pipelines (supporting alpha-channel WebM and high-efficiency HTML5 Canvas layers), the plugin maintains exceptionally low CPU and memory footprints. The pet operates in a floating desktop overlay with configurable global click-through support, ensuring that it never obstructs code editors, terminal windows, or IDE keyboard shortcuts. For users seeking customized setups, dsh-pet natively supports multi-pet concurrency, gravity-enabled dragging, smooth scaling from 50% to 300%, and flexible edge docking.
Expressive Physics Interactions and Autonomous Idle Actions
During dormant periods when no agent workflows are actively running, dsh-pet remains lively with contextual behaviors. The character incorporates over one hundred time-aware situational micro-animations: stretching in the morning, dozing off in the afternoon, or wandering along the taskbar during late-night coding sessions. Developers can interact with the pet using mouse gestures, including clicking, dragging, tossing across the desktop, and feeding, all rendered naturally via an integrated 2D physics engine.
Open-Source DIY Pet Pack & Creative Asset Pipeline
To empower every developer to adopt or design their own digital companion, dsh-pet features a modular Pet Pack specification. Asset definitions use transparent JSON declarations, supporting animations rendered as alpha-channel WebM, optimized GIFs, or APNG sprite sheets. The project includes an automated asset generation guide leveraging open-source AI video generators, enabling creators to transform character artwork into fully rigged, background-removed desktop pets with minimal manual keyframing.
Quick Start
Prerequisites and Plugin Installation
dsh-pet is optimized for the DeepSeek Harness official desktop application and DSHEAC bundles. Install the plugin using standard CLI commands:
# Install via dsh CLI on macOS and Linux
dsh plugin --profile desktop add https://github.com/PC2005-cloud/dsh-pet
# Install via Windows PowerShell
dsh plugin --profile desktop add https://github.com/PC2005-cloud/dsh-pet
For manual local source deployments, copy the codebase directly into the profile plugins directory:
# Copy files into the desktop profile directory
mkdir -p ~/.dsh/profiles/default/plugins/dsh-pet
cp -r /path/to/dsh-pet/* ~/.dsh/profiles/default/plugins/dsh-pet/
Launching and Configuring Your Desktop Companion
Restart the DeepSeek Harness desktop application after installation. Access the companion via the left sidebar under “Plugins → DSH Pet”, or dispatch terminal control commands:
# Launch the default desktop pet
/pet start
# Adjust scaling and dock placement
/pet scale 1.2
/pet dock bottom-right
# Toggle click-through mode to prevent focus interception
/pet click-through on
Declarative Configuration Example
Persist customized pet settings within your profile configuration:
# ~/.dsh/profiles/default/cordis.patch.yml
pet:
character: "default"
scale: 1.0
dock: "bottom-right"
statusSync:
thinking: true
tools: true
errors: true
physics:
draggable: true
collision: true
Frequently Asked Questions
Why is the pet window background opaque rather than transparent on macOS or Linux?
Transparent window rendering requires compositing support from the host operating system. On macOS, ensure that the application holds accessibility and window overlay permissions under System Settings. On Linux (X11 / Wayland), verify that a compositor (such as Picom or Mutter) is active. If a dark square background persists, navigate to plugin settings and switch the rendering engine from “WebM Alpha” to “Canvas Chroma Mode”, which automatically applies real-time edge color-keying to restore transparent rendering.
How can I disable speech bubbles during intensive model reasoning?
During deep reasoning or multi-turn refactoring loops, frequent thought bubbles may distract from focused development. You can mute text speech bubbles while keeping character animations active by unchecking “Show Status Bubbles” in the plugin settings panel, or by typing /pet bubbles off into the harness chat prompt.
How do I recover a lost pet window in multi-monitor configurations?
When external displays are disconnected or display resolutions change, floating window coordinates may remain positioned outside visible screen boundaries. To quickly recover a displaced window, execute /pet reset-position in the terminal. The pet will immediately glide back into the primary screen's safe bottom-right visible quadrant.
What are the recommended formats and resolutions for custom pet assets?
To maintain sharp visual fidelity without inflating video memory, the recommended resolution for sprite frames ranges between 256x256 and 512x512 pixels. For animated sequences, VP9-encoded WebM with alpha channels is strongly preferred over legacy GIFs, delivering 90% file size reductions and smooth anti-aliased transparency. For frame-by-frame sequences, use lossless WebP images. Refer to PET_PACK_GUIDE.md in the repository for format templates and packaging scripts.
