Generic DSH pet plugin
English | 中文
Runs animated pets in DSH Web using the Codex pet.json protocol. The plugin scans ~/.codex/pets/*/pet.json by default and includes Jiaran as a fallback asset.
Install
cd /path/to/deepseek-harness-desktop
pnpm dsh plugin --profile web add ./plugins/codex-pets
pnpm dsh web
Clicking waves, hovering jumps, and horizontal dragging runs in the matching direction. Double-clicking jumps and returns the pet to the bottom-right corner. Right-click the pet to cycle through discovered pets.
Add pets
A pet directory contains at least:
my-pet/
├── pet.json
└── spritesheet.webp
pet.json uses the Codex format:
{
"id": "my-pet",
"displayName": "My pet",
"spriteVersionNumber": 2,
"spritesheetPath": "spritesheet.webp"
}
Place the complete directory at ~/.codex/pets/<pet-name>/ and restart DSH. Desktop and plugin source do not need modification. This is the same installation directory and manifest format used by Codex. The plugin supports v1 (8×9) and v2 (8×11) atlases. Standard rows are idle, running-right, running-left, waving, jumping, failed, waiting, running, and review.
Configuration
Open Settings -> Plugins -> Plugin configuration to manage this plugin. The
card can show or hide the desktop pet, choose any discovered Codex pet, and
resize it from 50% to 200%. These values belong to codex-pets and are stored
under that namespace in the profile settings document.
Override plugin configuration in the profile's cordis.patch.yml:
- id: codex-pets
config:
activePet: my-pet
codexPetsRoot: /path/to/codex/pets
petDirectories:
- /path/to/another-pet
activePet: initially selected pet id.codexPetsRoot: automatically scanned root, defaulting to ~/.codex/pets.petDirectories: additional individual pet directories.
The configuration card is removed with the plugin. Removing codex-pets also
removes its codex-pets settings section; other plugin and product settings
remain untouched.
Session activity
The number badge beside the pet shows active session count. Clicking it opens a list containing the current or background running sessions, sessions awaiting input or plan review, and unread completed sessions. Clicking a row opens that session in DSH.
State mapping
- The first activity is running: running.
- The first activity awaits approval, an answer, or plan review: waiting.
- The first activity is an unread completion: review.
- The current session has an Agent error and no activity: failed.
- No activity: idle.
Frame counts, per-frame timing, return to slow idle after three action loops, activity priority, and drag thresholds follow the Codex state machine.
Uninstall
cd /path/to/deepseek-harness-desktop
pnpm dsh plugin --profile web remove codex-pets
Desktop destroys the plugin-declared transparent window after removal. The main interface, settings, and pet directory retain no plugin-injected state. User-installed assets under ~/.codex/pets are not deleted.
