dsh-clawd
A pixel pet for the DeepSeek Harness Web GUI. It sits in the corner, follows
what the Harness is doing — thinking, running tools, waiting for your approval,
finishing a turn, failing, compacting, juggling subagents — falls asleep when
nothing happens, and can be dragged anywhere.
turn/start → thinking approval/asked → waiting for you
tool/call → working compaction/start → compacting
turn/end 完成 → done (one-shot) subagent session → juggling
tool/result 失败 → error (one-shot) idle 3 min → yawns, dozes, sleeps
Nothing is guessed from the UI: the host half listens to the Harness'
session/event feed, folds it into the pet's state, and publishes the result.
The browser half only renders what it is told.
Install
# from a checkout, into the profile that serves this GUI:
dsh plugin --profile web add link:/absolute/path/to/dsh-clawd
Or, from the Harness itself, install the bundle
link:/absolute/path/to/dsh-clawd through plugin_manager.
The plugin activates immediately; the pet appears in the bottom-right corner
behind Settings → Clawd.
Bring in Clawd, Calico and Cloudling
This repository ships only artwork it is allowed to redistribute (the
placeholder theme, MIT). Everything else belongs to the clawd-on-desk
project and is All Rights Reserved — Clawd is Anthropic's character, Calico is
© 鹿鹿 — so none of it is committed. If that project is installed on your
machine, one command materializes all of its bundled themes locally, into
the git-ignored assets/local-themes/:
node scripts/setup-local-art.mjs --from /path/to/clawd-on-desk
# OK calico (15 states, 28 files, 11469 KiB)
# OK clawd (15 states, 48 files, 344 KiB)
# OK cloudling (15 states, 29 files, 563 KiB)
# then: Settings → Clawd → Reload themes
Nothing is copied verbatim from upstream: each theme.json is translated
into this plugin's manifest schema (states, tiers, idle pool, reactions,
timings, content box), and upstream's own scaffold theme is skipped. --link
symlinks the artwork instead of copying it (~12 MiB saved); --only clawd,calico
selects themes; --force regenerates ones already materialized.
When a theme's artwork renders empty
Some upstream exports paint nothing in an <img>: their character is assembled
by an inline script, which the browser never runs for an <img> (upstream
renders those files through a live <object> instead). Cloudling ships eight
such files — sweeping, carrying, sleeping, building, the sleep
transitions — which would show an empty frame.
npm run audit-local-art renders every referenced file in headless Chromium,
measures the painted pixels inside the theme's contentBox, and writes
audit.json next to the theme. The plugin reads that file and substitutes the
idle pose for a state whose only artwork paints nothing. Two caveats, both
honest limitations rather than oversights:
- A file that paints a fragment of the character (cloudling's
juggling shows
only the paper plane, conducting only a baton) cannot be told apart from a
legitimate pose by measurement — silhouette statistics flag real poses such as
Calico's carrying animation too. Those two are listed under
manualUnrenderable in the audit, which every re-run preserves; edit that list
to curate a theme by hand.
- Nothing here executes scripts from theme artwork.
<img> is used throughout
precisely because it does not, so third-party art cannot reach into the GUI's
document.
See Licensing and provenance for why the plugin is
built this way.
Settings
Settings → Clawd: show/hide, theme, size, opacity, a chime on turn end, reset
the position, reload themes. Defaults also come from the plugin's row in
cordis.patch.yml:
- insert:
- id: dsh-clawd
name: dsh-clawd
config:
enabled: true
theme: clawd
size: 64
User changes are stored in $DSH_HOME/dsh-clawd/settings.json and win over the
row config. Position is stored there too, and is written when you finish
dragging.
Themes
A theme is a directory with theme.json plus its artwork. Lookup order, later
roots winning on id collision:
| Root | Purpose |
|---|
assets/themes/ | themes shipped with the plugin |
assets/local-themes/ | local-only artwork (git-ignored) |
$DSH_HOME/dsh-clawd/themes/ | themes you add at runtime |
$DSH_HOME/dsh-clawd-themes/ | same, flat alternative |
node scripts/create-theme.mjs my-cat --name "My Cat" # scaffold from the MIT placeholder
node scripts/validate-theme.mjs # validate every root
theme.json fields: schemaVersion (must be 1), id, name, author,
description, viewBox, contentBox, objectScale, states ([file] or
{ files, fallbackTo }), workingTiers / jugglingTiers
([{ minSessions, file }]), idleAnimations ([{ file, duration }]),
reactions (drag, clickLeft, clickRight, double, annoyed), timings.
states.idle, states.working and states.thinking are required; artwork may
live beside theme.json or in an art/ subdirectory, and may be SVG, PNG, GIF,
APNG, WebP or JPEG. SVG with embedded CSS @keyframes plays natively in an
<img>, which is what the built-in themes use.
toolPoses dresses specific tool calls. It exists because some calls look like
something in particular: job_output either reads a little output or parks the
agent on a long poll, and the two read very differently. A theme maps a tool to
one file, or to { short, long } and lets the call's own timeout_ms decide —
timings.longWaitMs (default 30000) is the boundary, and wait: true without a
timeout counts as the longest wait. A tool a theme does not list keeps the busy
state's artwork, so toolPoses is purely additive:
"toolPoses": {
"job_output": { "short": "clawd-idle-reading.svg", "long": "clawd-sleeping.svg" },
"job_list": { "short": "clawd-idle-reading.svg" }
}
The bundled themes derive this from their own artwork rather than from a table of
names: a theme with a *reading* file reads for a short poll, and its static
sleeping poster (or its sleeping state) is the long one. Calico has no reading
art, so it only sleeps.
A reaction is either a one-shot or a held pose: drag shows for exactly as long
as the pointer is down (the client holds it and releases it on pointerup, blur,
or unmount), while clickLeft, clickRight, double and annoyed play for
their duration (default timings.reactionMs). Give a held kind no duration;
one is ignored for it.
contentBox is the rectangle inside viewBox that the character actually
occupies. The settings "size" is the height of that rectangle, so artwork with
generous transparent margins — the Clawd set draws a 23×20 cat inside a 45×45
viewBox — still fills the size you asked for. Omit it and the whole viewBox is
the content.
How it is put together
lib/state.js the ONE state table: names, priorities, one-shots, timings,
the session-event fold. Host, scripts and validator read it;
the browser half has no copy of it.
lib/machine.js the state machine: per-session records, one-shot queue with
minDisplay/autoReturn, approval & compaction holds, the idle →
sleep chain, the dominant-state resolution. Injectable clock.
lib/theme.js theme discovery, validation, state → artwork resolution.
lib/index.js host half: session/event wiring, settings store, and the
/dsh-clawd/ routes (state.json, live SSE, art, themes.json,
guarded settings/react/refresh writes).
lib/client.js browser half: shell.overlay pet + settings.section page.
Routes are registered under one prefix and never accept a path from a request:
artwork is served by looking a name up in the table built from the validated
manifests. Every route runs the Harness' own Host/Origin + browser-auth fence
(connection.requestRejection) plus a loopback/same-origin check.
Development
npm test # node:test suite over the state machine, host and client halves
npm run check # syntax-check every entry point
npm run validate-theme # validate every theme this plugin can see
npm run setup-local-art -- --from /path/to/clawd-on-desk
npm run audit-local-art # measure what each theme's artwork actually paints
Editing lib/client.js hot-reloads in the browser (the Harness' client HMR
watches the served bundle). Editing the host half needs a plugin reload or a
Harness restart.
Supported Harness versions
| Declared in | Field | Meaning |
|---|
package.json | dsh.engines.dsh = >=0.1.7-rc.1 | advisory range, read by tooling and marketplaces |
package.json | dsh.compatibility.dshReleases | per-release verdict; compatible means CI boots it |
.github/workflows/dsh-compat.yml | the matrix itself | one cell per release the plugin claims |
0.1.7-rc.1 and 0.1.7-rc.2 are the declared releases; everything older is
unknown, not "unsupported" — the APIs this plugin calls have existed since
0.1.2-rc.1, but only the declared cells are verified by CI, and a claim CI does
not check is a guess.
Note what enforces a version and what merely documents it. The Harness' install
gate evaluates peerDependencies named @deepseek-ai/dsh* against the
running version (prereleases included) and refuses a mismatch with
incompatible-version unless an exact-version exemption is granted. This package
declares no such peer on purpose: the plugin imports nothing from the Harness
at runtime — it speaks to it through Cordis services and events — so a hard gate
would block installs for no measured reason. dsh.engines and
dsh.compatibility are the declaration; the compatibility workflow is the proof.
Three builds
| Command | Ships | Use it for |
|---|
npm run pack | everything, including the MIT placeholder theme | a clone-and-run install that renders immediately |
npm run pack:no-art | the same code with assets/themes/ removed | destinations that supply their own artwork, or must carry none |
npm run pack:local-art | plus the locally materialized Clawd/Calico/Cloudling themes | the author's own machines — never publish this one |
A theme-less build is not a broken build: the host half mounts, the pet stays
hidden, and Settings → Clawd says no theme is available — add one through
$DSH_HOME/dsh-clawd/themes/, npm run create-theme, or
npm run setup-local-art.
The third build exists so a personal install does not have to re-run
setup-local-art on every machine: it copies assets/local-themes/ into the
tarball (dereferencing symlinks, so nothing points back at this checkout) and
drives the packaged clawd theme to prove it resolves. It carries artwork that
is All Rights Reserved — the Clawd character is Anthropic's, the Calico cat
is © 鹿鹿, and none of it is covered by this repository's MIT license — so the
command prints a warning and writes a LOCAL-ONLY.md marker into the tarball
itself, and scripts/pack-variant.mjs refuses to build it without --personal.
The two distributable builds are the first two.
scripts/pack-variant.mjs takes --without <path> and --with <path>
(repeatable), --personal, --label, --version-suffix and --out; drop the
plugin icon too with --without assets/themes --without assets/branding. All
builds keep the same name@version unless you pass --version-suffix, so
publishing two of them side by side to one registry wants a suffix.
Releasing
Tag v<version> matching package.json and the release workflow runs the same
gate as CI, packs dsh-clawd-<version>.tgz, writes SHA256SUMS.txt, and attaches
both to the GitHub Release. There is no npm publish: a bundle is consumed as a
tarball or a checkout.
git tag v0.1.0 && git push origin v0.1.0
Licensing and provenance
| Part | License | Redistributed by this repository |
|---|
lib/, scripts/, test/, cordis.patch.yml, this README | MIT (LICENSE) | yes |
assets/themes/placeholder/, assets/branding/icon.svg | MIT, drawn by scripts/make-placeholder-art.mjs | yes |
assets/local-themes/ | All Rights Reserved | no — git-ignored, never packaged |
artwork a user drops into $DSH_HOME/dsh-clawd/themes/ | the user's own | no |
The local themes are materialized by scripts/setup-local-art.mjs from an
installed clawd-on-desk checkout, whose assets/LICENSE states All Rights
Reserved — explicitly outside that project's source license, permitting only
personal use of the app it ships with. Its artwork is therefore copied (or
symlinked) into a git-ignored directory on the user's own machine, and
package.json files never lists it. Clawd is Anthropic's character: this
is an unofficial, non-commercial fan work that claims no rights in it and
distributes none of it.
Two boundaries worth stating:
- The artwork audit (
npm run audit-local-art) only measures those files. It
executes nothing from them, and the plugin renders every theme through <img>
— never <object> — so no theme file's script can reach into the GUI.
- The state vocabulary, priority order and theme field names follow the
clawd-on-desk protocol (AGPL-3.0-only source). Protocols, data formats and
interface names are not copyrightable expression and no source file from that
project was copied: lib/ is an independent implementation of the format.
The long-form documents this plugin was developed against — the specification,
the item-by-item provenance inventory, the two research reports — are working
material and live in docs/ on the author's machine only; docs/ is
git-ignored and is not part of any release.
