dsh-obvious-grid

dsh plugin --profile web add dsh-obvious-grid

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 Harne

…(truncated)