dsh-obvious-grid
npm: dsh-obvious-grid · source: github.com/ray062/dsh-obvious-grid
Host plugin for DeepSeek Harness: makes session status obvious — visible from
across the room and reaching you when you are AFK. Port of the idea of
opencode-obvious-grid (its "HOW":
an ambient glanceable grid + push/alarm on turn-finished / error / approval-wait),
onto DSH's own seams instead of opencode hooks + temp files.
What you get
- Ambient grid page served by the harness itself at
/obvious-grid (web profile):
a fullscreen port of opencode-obvious-grid's UI — distance-readable cards that
fill the viewport, the whole card tinted by state: orange = running (with a
giant scrolling RUNNING marquee), blue = waiting / blocked on you
(flashing attention), red = error, green = idle. Cards show the
session title (folded from the log-only session/title event, seeded from
ctx.sessionTitle at adoption), workspace path · git branch (read from
.git/HEAD up the directory tree), model/provider, per-request tokens
(current request) + session totals, reasoning tokens (usage-reported when the
adapter provides them, otherwise counted from the token-sized
reasoning-delta stream chunks — the harness's own token boundaries),
context-window % (the RAW prompt
footprint of the newest measured request — uncached input + cache read over
the window, NOT the session-cumulative cache total which would inflate the
gauge to 100%+), prompt-cache hit % (last request | session average),
token/s speed (last | average), per-state time breakdown (run/wait/idle/err)
- pid + llm time in the meta line, sub-agent
↳ + parent line, per-card
sound/notify toggles, hide/restore, and live per-request graphs (token usage
stacked bars + token/s rate and average lines, hover for per-request detail
with cumulative totals).
Zero interaction required; the page polls /obvious-grid/status and stays live.
The state follows the session’s open turn: running covers the whole
turn — each step, the gaps between steps (tool calls), and compaction
(compaction/start..compaction/end) included — so the grid never flickers
to idle between steps, and a manual /compact between turns shows as running
while the summary is being produced. Idle only when no turn is open.
- AFK notifications on exactly three triggers (obvious-grid semantics):
turn-end — a turn finished, come look;error — agent/error on the live bus;approval-wait — an approval/asked is parked, you are the blocker.
Each trigger pushes to ntfy (phone) and/or plays an alarm on the machine.
Per-session opt-in toggles + a global topic, changed from the page; a global
notifyDefault switch in config opts all sessions in.
- History resumes across restarts: DSH never rebroadcasts constructor
seeds (replay/fork/resume) on the
session/event firehose, so the registry
folds each session's full event log (session.events) once at adoption —
turns/steps/tokens/title from before a harness restart reappear, the
opencode-obvious-grid behavior. Live appends keep coming from the firehose,
and the two sources are disjoint (no double counting).
- Nothing new to run: no own HTTP server (routes register on the harness
webserver), no temp-file registry, no PID liveness / staleness window. The
page file is read fresh per request, so UI edits appear on a browser refresh
without a harness restart.
Install
dsh plugin --profile web add dsh-obvious-grid
dsh plugin --profile web add @deepseek-ai/schemastery
dsh web # restart, then open http://localhost:3080/obvious-grid
That's it — the package ships a dsh.bundle manifest (its own
cordis.patch.yml), so dsh plugin add registers the plugin as a profile
layer automatically: no manual patch editing, no config file. (dsh plugin
forwards pnpm; for local development a tarball or file: path works the same
way, e.g. dsh plugin --profile web add file:/path/to/dsh-obvious-grid.)
User-specific config (optional)
Per-user settings — your ntfy topic, alarmCmd, push defaults — belong in
the profile's own patch layer $DSH_HOME/profiles/web/cordis.patch.yml as an
id-targeted override (only the keys you set are needed):
- id: obvious-grid
config:
topic: my-dsh-alerts # ntfy topic; push is off until set
notifyOn: [turn-end, error, approval-wait]
notifyDefault: false # true = notify all sessions unless overridden
alarmCmd: "" # e.g. paplay /usr/share/sounds/freedesktop/stereo/complete.oga
minIntervalMs: 5000 # max one push per session per interval
ntfyUrl: https://ntfy.sh
pageEnabled: true
Note for setups from before v0.2.0: if you previously registered the plugin by
hand via an insert row in your profile patch, remove that row after
Troubleshooting
file: / tarball installs are snapshots, not live links. pnpm copies the
package at install time, so after changing the source repo you must reinstall
(re-run dsh plugin --profile web add file:/path/to/dsh-obvious-grid) —
otherwise the installed copy silently keeps stale files. The npm-package
install (dsh plugin --profile web add dsh-obvious-grid) avoids this.- Bundle not active after a
dsh plugin command? The reconciler maintains
dsh.profile.bundles from installed state — the entry is added when the
installed package declares dsh.bundle, and removed when it doesn't. If
your copy is stale (see above), the manifest may be missing: refresh the
install, then check dsh.profile.bundles in the profile's package.json
contains dsh-obvious-grid.
- Quick sanity check:
/obvious-grid/status must return JSON. If it
returns the SPA shell (DeepSeek Harness app HTML) instead, the plugin did not
register — check the two bullets above.
Config
| Key | Default | Meaning |
|---|
ntfyUrl | https://ntfy.sh | ntfy server base |
topic | "" | ntfy topic. Empty = push disabled (page can set it at runtime) |
notifyOn | [turn-end, error, approval-wait] | which triggers push |
notifyDefault | false | notify sessions that have no explicit per-session flag |
alarmCmd | "" | optional alarm shell command; unset = silent |
minIntervalMs | 5000 | per-session push throttle |
pageEnabled | true | mount the /obvious-grid routes (web profile) |
Runtime user config (topic + per-session toggles) lives in
$DSH_HOME/obvious-grid.json and is editable from the page
(POST /obvious-grid/notify).
Endpoints (web profile)
| Route | Description |
|---|
GET /obvious-grid | the ambient page (plain HTML file, zero build) |
GET /obvious-grid/status | JSON snapshot of live sessions |
GET /obvious-grid/notify | current topic + per-session flags |
POST /obvious-grid/notify | set topic and/or toggle one session |
Files
dsh-obvious-grid/
lib/index.js plugin entry: name, Config (schemastery), apply()
lib/sessions.js live per-session fold of the session firehose
lib/notify.js ntfy push + bounded alarm subprocess + user config store
lib/page.html the ambient grid page (plain file, no template processing)
cordis.patch.yml bundle patch layer (dsh.bundle manifest) — auto-registers the
plugin on `dsh plugin add`, no manual patch editing
scripts/check-page-script.mjs syntax-checks the page's embedded <script>
scripts/seeder.mjs test seeder: creates a multi-session grid (parent +
sub-agent + extra session) in an isolated profile to
exercise several cards without touching a live instance
Safety rules (kept from the original plugin)
- No top-level side effects;
apply(ctx, config) does all wiring.
fetch is always bounded (AbortController, 3 s); the alarm subprocess is
detached, unref'd, stdio ignored, killed after 5 s — it can never hang
the harness.- All file config I/O swallows errors; a broken store must not break the page.
lib/page.html is a plain file — no template processing. The embedded script
uses only string concatenation (no template literals), and npm run check
syntax-checks it.
Verify
npm run check # node --check on lib/*.js + the extracted page script
Verification limits: this package was written against the published
@deepseek-ai package contracts (dsh-session-telemetry event subscription,
dsh-host-webserver route registration, dsh-session-title-first-prompt-llm
plugin shape, dsh-session-stats event vocabulary) and has been live-loaded
against DSH rc.6 in this environment: boot failed until the loader entry declared
inject: [sessions, webServer, sessionTitle] (cordis forbids touching
undeclared services), and apply() now reads services through a guarded
accessor so a missing service degrades instead of killing the boot. A
multi-session grid (parent + sub-agent + second session, waiting + idle states)
is exercised by scripts/seeder.mjs in an isolated profile. A load failure
still surfaces in the Loader log; the Logger row message names the missing
export, schema field, or service.
Differences vs opencode-obvious-grid
- Data source: DSH session firehose (
session/event) instead of opencode hooks;
no temp state files, PID liveness, or staleness window.
- Server: routes on
ctx.webServer instead of a plug-in-owned port + takeover;
no platform player discovery (powershell/afplay/paplay) — alarmCmd is the
user's own shell command.
- Cost: DSH reports no message cost today, so cards show tokens + wall times
instead of $. If providers expose usage cost later, it drops into the same fold.
- Fleet: v1 shows the serving instance's live sessions. A machine-wide grid over
several concurrent
dsh processes would scan the shared canonical logs under
$DSH_HOME — the open 20%, deliberately deferred.
License
MIT. Idea and page design derive from
ray062/opencode-obvious-grid (MIT).
