dsh-pixel-companions
一个可拖动的动画像素伙伴，可悬浮在 DeepSeek Harness Web GUI 的任意位置，并跟随代理执行打字、工作、等待你、完成和睡眠等状态。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:kappyra/dsh-pixel-companions#f212011100483fc63b2d9abf54def825d982bc76
Pixel Companions 以 dsh-pixel-companions 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文 | Русский | Tiếng Việt | 日本語 | 한국어
I built Pixel Companions because I wanted my dsh sessions to feel less faceless. It is an animated pixel companion that floats above the whole DeepSeek Harness (dsh) Web GUI and follows what the agent is doing: typing, working, waiting for your approval, done, sleeping. I render it in the frame-wide overlay, so it stays visible on every page — a conversation, Settings, Plugins — and you can drag it anywhere in the window. I kept it a normal opt-in dsh bundle: no fork of the UI, no patched core, no prompt or response interception. I'm kappyra, and this is my side project for dsh.
I drew two characters, each with 15 animated scenes:
Artwork. Deepy uses the v3 matte pixel set I picked; Whale Girl keeps the pack's v2 style. All sprites are 192×128 and transparent.
My companion is a browser-side contribution to the official frame-wide shell.overlay
slot. A hidden bridge entry in conversation.input.dock publishes session facts into the
plugin's own module store, and the overlay reads them. The gear button opens a small
settings popover that I keep in localStorage for this browser only (see Configuration).
kappy.pixel-companions.ui.v1 as position: {x, y} (null until the first drag). Until
then I place it automatically in the bottom-right above the composer area and follow
window resizes.roaming animation while dragged. I serve sprites from the
plugin's own asset route and fetch them per scene, so the JS bundle stays small.navigator.language,
else English.dsh web) — I target the official Web client only.pnpm on PATH, because dsh plugin forwards package operations to pnpm.client.js.I ship the package as a prebuilt bundle: client.js and the artwork under assets/ are
committed, so installing needs no build step.
git clone https://github.com/kappyra/dsh-pixel-companions.git
cd dsh-pixel-companions
dsh plugin --profile web add link:"$PWD"
link: keeps the profile pointed at your working copy, so later edits under assets/
or src/ (followed by npm run build) are served immediately.
dsh plugin --profile web add github:kappyra/dsh-pixel-companions
# or, after `npm pack` in the checkout:
dsh plugin --profile web add /path/to/dsh-pixel-companions-0.1.0.tgz
Then reload the Web page. Adding a bundle enables it in the profile; the companion appears near the bottom-right on every page — conversation, Settings, Plugins — and survives page navigation. The client HMR transport usually swaps the bundle in within a second or two anyway; a reload is safe.
Full flow (Plugins page, enabling, disabling, uninstalling, troubleshooting): docs/installation.md. Day-to-day use — dragging, the hover message box, the sticky report and its details, sizing, languages and the desktop window — is in docs/usage.md.
I keep all settings in the panel opened from the companion or its gear button (⚙):
| Control | What it does | Stored as |
|---|---|---|
| Character | Lumi or Deepy | kappy.pixel-companions.ui.v1 |
| Size | 50–200% slider in 5% steps, with −/+ buttons, a live readout and 50/100/150/200% preset chips; the sprite renders at real pixel size | same key |
| Companion size (Settings → General) | The same slider, −/+ buttons, readout and presets as the gear popover; both edit the shared preference and stay in sync | same key |
| Language | English, Русский, 中文, Tiếng Việt, 日本語, 한국어 | same key |
| Motion | Animated WebP or a still PNG | same key |
| Visible | Show or hide the companion | same key |
| Desktop window | Mirror the scene into the optional desktop window; status Off / Not running / Connected | same key |
| Reset position | Return the companion to its automatic bottom-right default | same key |
| Test scene | Force any of the 15 scenes, or return to automatic (Auto) | session state only |
| Close | Close the panel; Escape or an outside click also closes it | — |
I anchor the panel to the companion, flip it above or below automatically, and clamp it to the viewport. Preferences and the dragged position are per browser and per profile, never written to the Host settings service; the plugin adds no separate Settings page — its size row appears in Settings → General.
I also built the same companion as a desktop window: it can run outside the browser in a frameless, always-on-top, per-pixel-transparent window on the same machine. It is off by default.
sudo apt install python3-gi gir1.2-gtk-3.0 python3-cairo
python3 -m pip install --user Pillow
python3 desktop/companion.py # or ./desktop/run.sh
Tick Desktop window in the gear panel; the row shows Connected, Not running, or Off. Only the scene id, character, scale, and motion flag cross the localhost bridge — no prompt text, draft, messages, session ids, file paths, or model output. See docs/desktop.md.
| Observed signal | Scene | Honest meaning |
|---|---|---|
Prompt submitted (input.phase = sending/submitting/adjudicating) | typing | The message is being submitted |
| A tool call is running | working | A tool is executing |
| Assistant streaming reasoning | thinking | The model is reasoning |
| Assistant streaming answer text | typing | The model is writing the answer |
| Turn running, no live stream (request in flight) | thinking | Waiting on the model |
| Running > 75 s with no live signal | tired | Long task, not model fatigue |
| Running > 180 s with no live signal | coffee | Cosmetic only |
| Pending approval / question | waiting | Waits for you |
promptError, lastAgentError, or openState = error | error | A real error signal |
| Running → stopped without an error | success (sticky) | Stays with the report until you hover the companion or a new turn starts; may include cancellation |
| No activity for 110 s | sleeping | Display-only idle timer |
| Otherwise | idle | — |
I made the rules language-independent; only the captions under the companion are localized.
thinking means the assistant is reasoning — drafting a message in the composer changes
nothing. planning, reading, searching, debugging, and offline are
manual-preview only until the client exposes typed signals for them; the plugin never
guesses them from prompt words. Full rules: docs/scenes.md.
I verified it against a live dsh 0.2.2-alpha.2 Web profile: the bundle installs, the
Client module loads through the Harness module loader, the entries register in
shell.overlay (companion) and conversation.input.dock (hidden bridge), the served
bundle bytes match the repository, and the component renders with the real slot props.
docs/compatibility.md lists the exact APIs, the bridge → overlay
data flow, the six-language dictionaries, and the optional desktop bridge. Visual checks
(light/dark, drag feel, exact placement) are yours to confirm.
npm install # esbuild, dev-only
npm run build # build the asset manifest, then bundle client.js
npm test # unit tests (Node 22.6+)
Browser code: src/client/bridge.ts (facts store), Pet.tsx (overlay, drag and roaming,
hidden bridge, hover box, report), state.ts (scene rules), signals.ts and asset-url.ts
(pure helpers and asset-route resolution), text.ts (six languages), desktop.ts (optional
desktop bridge). I documented the pipeline, packaging and layout in
docs/development.md.
assets/, source-art/, demo/, and the copies the
plugin serves for this project; it ships with the project. It is not covered by the MIT
grant on the code, and I retain its rights. See ASSETS_NOTICE.md.| Symptom | Check |
|---|---|
| No companion anywhere | Settings → Plugins: is the bundle enabled? Reload the page. An open conversation is not required. |
| Companion visible but frozen | The still PNG may be selected (motion off) or the OS asks for reduced motion. |
| Companion does not move when dragged | Move a few pixels before releasing (there is a drag threshold), and drag the sprite itself, not the empty overlay. |
| Companion off-screen after resizing or changing monitors | Gear → Reset position; it returns to the automatic bottom-right default. |
| Sprite is too big or too small | Click a 50/100/150/200% preset chip or drag the Size slider (50–200%) in the gear popover or in Settings → General → Companion size; the saved position re-clamps automatically, and Reset position restores the automatic bottom-right spot. |
| Cannot find the size control | It is in Settings → General → Companion size and in the companion's ⚙ popover; both edit the same preference. If neither appears, a hard reload is needed (the page is running an old client bundle). |
| Wrong language | Gear → Language. The first run follows the browser language; otherwise it is English. |
| Settings popover clipped | The panel flips and is clamped to the viewport; Reset position, then report the window size. |
| Desktop window stays offline or is an opaque box | Page open and Desktop window ticked; install python3-cairo for transparency; check curl http://127.0.0.1:37421/health. See docs/desktop.md. |
| Sprites are stale or 404 after changing the artwork | Run npm run build — the ?v= content hash is part of each sprite URL — then reload the page. |
client.js failed to load | The profile must serve the package; run dsh plugin --profile web add again and check the pnpm log under $DSH_HOME/profiles/web/.plugin-manager/logs/. |
More in docs/troubleshooting.md.