A floating pet in the bottom-right corner of the DSH Web GUI that switches its animation in real-time based on the current session status: running, waiting, error, or completed.
- Language
- JavaScript
- License
- MIT
- Branch
- main
Install
$ dsh plugin --profile web add github:minybear/DeepSeek-Harness-PetRun the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial
Install via your agent
Install the DeepSeek Harness plugin minybear/DeepSeek-Harness-Pet for me: review the repository at https://github.com/minybear/DeepSeek-Harness-Pet first, then run the install command and verify the plugin loads successfully.
Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.
Quick Summary
Raise a floating pet in the bottom-right corner of the DeepSeek Harness (DSH) Web client—the pet's animation, status bubbles, and nurturing stats are real-time linked to the agent's running state in the current session: when the agent is working, it runs on gears; when waiting for your input, it raises its hand asking for action; when it crashes during runtime, it rolls its eyes and lies flat.
Core Features
- Real-time mapping of agent status to 9-segment official animations: running while working, raising hand when waiting for input, lying flat on error, celebratory jump right after completion, waving hello when switching sessions
- 5 built-in pets available: Dee (teal green), Amber (amber), Berry (berry purple), Gray Whale (DeepSeek Harness logo shape), Blue Whale (DeepSeek official brand blue shape)
- Nurturing stats system: 🍖 Fullness / 😊 Mood 0–100, decays in real time (even with browser closed), feeding +30, playing +25; automatic prompt when either stat drops below 20 in idle state
- Click to pop up 🍗 Feed / 🎾 Play / ⚙ Settings menu; drag to move position (position persisted to localStorage); size 0.5–1.5, transparency 0.2–1 fully adjustable
- Support importing official Codex pet packs (
pet.json+ atlas), validated and stored to localStorage, can switch or delete anytime - Follows system "reduce motion" preference or manual lock, shows fixed idle first frame when enabled
- Built-in bridge mode: POST session state to
http://127.0.0.1:8765/pet-statefor desktop clientdsh-pet-desktopfloating window consumption
Technical Implementation
- Language: JavaScript (ESM)
- Key Dependencies:
@deepseek-ai/dsh-client-runtime^0.1.0-rc.6、@deepseek-ai/dsh-client-ui-slots^0.1.0-rc.6、@deepseek-ai/cordis^4.0.1、react^18.2.0 - Architecture Pattern: Dual-end injection—host side
lib/index.jsis emptyapply(placeholder registration), browser side loaded viapackage.json#dsh.client.injectexportingexports["./client"], loaded bywindow.__ModuleLoader__; writesui-petto browser roster viacordis.patch.yml; injects two components toshell.overlayslot at runtime:PetOverlay(visible pet) andBridgeOverlay(no-UI state bridge) - Entry Files:
lib/client.js(browser main),lib/index.js(host side empty placeholder),lib/pet-core.js(DOM-free pure logic layer, state machine + pet.json parsing + frame index + decay)
Use Cases
Users who spend long time staring at DSH Web waiting for agent tasks, wanting some companionship on their work interface. Suitable for those who find logs boring and want to judge the agent's current state at a glance through the pet's movements; not suitable for scenarios requiring serious backend monitoring or maximizing screen space (pet occupies bottom-right floating layer by default, can be dragged away but cannot be completely hidden).
Prerequisites & Compatibility
| Dependency | Min Version | Description |
|---|---|---|
| DSH (dsh-client-runtime) | ^0.1.0-rc.6 | Declared by peerDependencies, pnpm will fetch corresponding host version during installation |
| DSH client UI slots | ^0.1.0-rc.6 | Same as above |
| @deepseek-ai/cordis | ^4.0.1 | DSH internal plugin framework |
| react | ^18.2.0 | Pet UI rendered with React |
| Platform | Cross-platform | Only requires DSH Web GUI with modern browser support; no native module dependencies |
| Node.js | Not declared | Package does not declare engines; test scripts use node test/*.mjs, but end users don't need local Node |
Installation
dsh plugin --profile web add github:minybear/DeepSeek-Harness-Pet
Configuration Options
| Option | Type | Description | Default |
|---|---|---|---|
| Pet | Dropdown select | One of 5 built-in pets + user-imported custom pets | Dee (teal green) |
| Size | Slider 0.5–1.5 | Overall scale multiplier of the pet | 0.9 |
| Transparency | Slider 0.2–1.0 | Overall opacity of pet and bubbles | 1.0 |
| Animation | Dropdown select | Full animation / Reduce motion / Auto (follows system prefers-reduced-motion) | Auto |
| Feed / Play | One-time action | Click menu 🍗 / 🎾 to execute immediately, triggers 2.2s / 2.6s interaction animation and restores nurturing stats | — |
| Position | Drag | Drag pet to any screen position, persists after refresh | Bottom-right (16px from edge) |
FAQ
Q: Didn't see the pet after installation?
A: Client plugins require host-side packaging and take effect after restarting dsh web. After installation completes, you must restart the dsh web process and refresh the page (default http://127.0.0.1:3080) for the pet to appear in the bottom-right corner.
Q: Do I need to write code or configuration separately?
A: No. The plugin uses the built-in teal green pet Dee by default, ready to use out of the box; size, transparency, animation mode, and pet selection are all adjustable through the settings panel, no config file editing needed.
Q: Can I switch to my own pet?
A: Yes. The settings panel provides "Import Codex Pet Pack", provide manifest file and atlas images (PNG/WebP/GIF, <2MB) in official pet.json format to import, after validation passes it's stored to localStorage, can switch or delete anytime.
Q: Will the pet starve if I close the browser?
A: Yes. Fullness and mood stats decay by wall clock time (≈8 hours / 6 hours to zero), continues timing even when browser is closed, after reopening values are calculated from last update timestamp.
Q: Where is data stored? Does it sync to cloud?
A: All stored in browser localStorage (dsh-pet:* namespace), including pet selection, position, size, nurturing stats, imported custom pets. This plugin does not send any network requests (unless dsh-pet-desktop desktop floating window is also installed, then pushes state to local 127.0.0.1:8765).
Q: What does "reduce motion" mean? What happens to the pet when enabled?
A: Reduce motion mode (system settings or this plugin's settings panel) fixes the pet displaying the first frame of idle animation, no motion playback. This is standard response to system prefers-reduced-motion, helps users with motion sickness use DSH.
Q: Can I hide the pet but keep it installed?
A: Cannot directly "hide", but can set transparency to 0.2 or drag to screen corner; to completely remove please use dsh plugin --profile web remove @minybear/dsh-pet to uninstall.
Q: What's the difference between the five pets?
A: Three blob-style pets (Dee/Amber/Berry) share the same 12-frame walk/wave/jump/lie down animations, only colors differ; two whales (gray whale/blue whale) are side-view, bubbles appear while working, water spray in idle, chest fin raises during wave, overall mirrored for direction.
Difficulty Level
Beginner — install and use immediately, no code writing or config editing; advanced players can import custom Codex pet packs or adjust transparency/size/animation strategy.
Known Issues & Limitations
- Current version has no active TODO/FIXME; historical issues (such as React hooks order violations, pet-core and client inline copy state machine divergence, install script hardcoded paths) all fixed in versions 0.2.0/0.4.0
- Custom pet atlas size limit ~3MB (including base64 encoding), imports rejected when exceeded with prompt "Please use WebP/PNG under 2MB", compress with ImageOptim etc. before importing
- Only 9-line Codex V1 official atlas can enjoy full state machine animation; custom pets lacking interaction rows (eat/play/drag) fall back to idle row during interaction
- BridgeOverlay bridge mode enabled by default, sends requests to
http://127.0.0.1:8765/pet-state; if no companion desktop floating window running, requests are silently dropped but visible in DevTools Network panel
Codex 风格的「桌面宠物」DSH 客户端插件:在 DeepSeek Harness(DSH)Web GUI 里漂浮一只动画小宠物,由当前会话的 agent 运行状态实时驱动(工作 / 等待输入 / 报错 / 刚完成 / 待机)。
复刻对象:OpenAI Codex 桌面版的 Pets 功能。调研结论见
docs/Codex-Pet-能力分析.md与docs/复刻方案.md;与 Codex 官方能力的逐项对照见docs/差距分析.md;版本变更记录见CHANGELOG.md。
能力
-
漂浮宠物:注册进 DSH 的
shell.overlay槽(帧级浮动层,可点透,右下角常驻,可拖拽换位)。 -
状态驱动:读当前会话状态并映射到 Codex 的 9 状态动画行;会话信号按 Codex
ambient.rs的存活期衰减(Running 3min / Failed 1h / Waiting 24h / Review 7d,超时回退 idle):DSH 信号 宠物状态(行) 状态标签 running === truerunning(7) Running pendingInteractionwaiting(6) Needs input lastAgentErrorfailed(5) Blocked running true→false边沿jumping(4) Done!(约 2.6s) completedreview(8) Ready 切换/打开会话 waving(3) Hi!(约 1.7s) 拖拽移动中 running-left/right(1/2,按方向) (无) 无活动 idle(0) (无) -
减少动态:跟随系统
prefers-reduced-motion,或在设置里手动锁定「完整 / 减少动态」;减少动态时按 Codex 行为固定显示 idle 第一帧。 -
交互:
- 点击 → 弹出菜单:🍗 喂食(
eat)、🎾 玩耍(play)、⚙ 设置。 - 拖拽 → 移动宠物位置(按拖动方向播放官方 running-left/right 行走动画,静止时为
drag姿态,位置持久化到 localStorage)。
- 点击 → 弹出菜单:🍗 喂食(
-
养成数值:🍖 饱食 / 😊 心情 0–100,随墙钟时间衰减(关掉浏览器也计时,约 8h / 6h 见底);喂食 +30 饱食、玩耍 +25 心情;菜单里有两条数值条,待机且某项 <20 时宠物会冒「🍖 饿了 / 🎾 想玩」提示。
-
多宠物:内置五只宠物——Dee(青绿)/ Amber(琥珀)/ Berry(莓紫)同模配色,以及灰鲸(DeepSeek Harness logo 造型)/ 蓝鲸(DeepSeek 官方 logo 造型,品牌蓝)两只侧视鲸鱼,设置面板一键切换。
-
自定义宠物导入:设置面板可导入标准 Codex 宠物包(
pet.json+ 图集图片,如~/.codex/pets/下 hatch-pet 生成的宠物),校验后存入 localStorage 并立即可选;可删除。无额外交互行的官方 9 行图集会自动回退(交互态播放 idle 行)。 -
外观设置:尺寸(0.5–1.5)、透明度(0.2–1)、动画模式、宠物选择,全部持久化到
localStorage。 -
Codex 兼容包格式:宠物由
pet.json(id/displayName/description/spritesheetPath/frame/animations)+ 一张行优先图集(无独立 atlas 文件,帧索引index = row×columns + col)描述;内置默认宠物在运行时用 canvas 生成。前 9 行为 Codex V1 官方 9 状态,第 9–11 行为交互状态(eat/play/drag),经官方frame覆写(96×104×8×12)与animations字段声明。
结构
lib/pet-core.js 纯逻辑(Node 可测):pet.json 解析 + 帧切片 + 状态机 + 状态存活期
lib/index.js host 侧 apply(空,纯 UI 插件)
lib/client.js 浏览器侧:window.__ModuleLoader__.load + apply/inject + PetOverlay + 精灵生成
test/*.test.mjs Node 单测(pet-core + client 契约 + 双副本一致性)
docs/ 调研、方案与差距分析
注:
client.js内联了一份 pet-core(DSH 模块加载器无法解析包内文件),test/parity.test.mjs会对两份副本做全量行为一致性校验,防止分叉。
测试
npm test # 依次跑 pet-core / client-contract / parity
node scripts/render-atlas.mjs --all # 软渲染三只内置宠物图集并自检网格不变量
安装到 DSH
# 从 npm(发布后)
dsh plugin --profile web add @minybear/dsh-pet
# 或一条命令装本地 checkout(包自带 dsh.bundle.patch 自注册)
dsh plugin --profile web add .
# 或从 GitHub
dsh plugin --profile web add github:minybear/DeepSeek-Harness-Pet
然后重启 dsh web 并刷新页面,宠物应出现在右下角。离线环境或无需 pnpm 时,用 deploy\install.ps1 手动装;完整步骤见 INSTALL.md。
注:客户端插件需宿主端打包(
dsh.client.inject)与重启后生效。
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](https://deepseek-plugin.org/plugins/minybear/DeepSeek-Harness-Pet)Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.