Obvious Grid

dsh-obvious-grid Host plugin for DeepSeek Harness: makes session status obvious — visible from across the room and reaching you when you are AFK. The harness itself serves an ambient, glanceable status grid at /obvious-grid, and the plugin pushes to ntfy (phone) and/or plays an alarm on the machine when a turn finishes, an error occurs, or an approval is waiting on you. ## Install bash dsh plugin --profile web add dsh-obvious-grid # npm package name — resolved from the registry as-is dsh plugin --profile web add @deepseek-ai/schemastery # the plugin's config schema; an optional peer, so pnpm won't auto-install it 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-obvious-grid in the first command is the npm package name itself (published unscoped on npmjs.com), so a fresh install needs no scope or repo prefix: dsh plugin forwards the bare name to pnpm, which resolves it from the registry and adds it to the profile's dependencies; the reconciler then appends it to dsh.profile.bundles because the installed manifest declares dsh.bundle. The second line installs @deepseek-ai/schemastery as a plain dependency (it declares no dsh.bundle, hence the harmless "no dsh.bundle" warning) — it is required at boot because the plugin's entry imports it directly while declaring it only as an optional peer, and the web profile template sets autoInstallPeers: false. (dsh plugin forwards pnpm, which must be on PATH — it prints dsh: pnpm not found on PATH otherwise; 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.) ## How to use 1. Boot the harness: dsh web (or restart a running instance), then open http://localhost:3080/obvious-grid — the grid fills the viewport and updates itself; nothing to click to get started. 2. Read each session at a glance: the card tint is the state — orange running (scrolling RUNNING marquee), blue waiting on you, red error, green idle — and the card shows title, workspace · git branch, model/provider, tokens, context %, cache hit %, speed, and time breakdown. 3. Per-card controls: hide/restore a card, and toggle that session's push (ntfy) and sound (alarm) — or flip the global switch to opt all sessions in. 4. To be reached when AFK, give the plugin a ntfy topic and/or an alarm command — set them on the page, or statically in your profile patch (see "User-specific config" below). You are notified on exactly three triggers: a turn finishing, an error, and an approval waiting on you. 5. Sanity check: GET /obvious-grid/status must return JSON. If you get the app's HTML shell instead, the plugin did not register — see Troubleshooting. ## What you get - Ambient grid page served by the harness itself at /obvious-grid (web profile): 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. 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. ## 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). ## 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): yaml - 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 > upgrading — it duplicates the bundle's own insert. ## 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 | ## 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. ## 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 1. No top-level side effects; apply(ctx, config) does all wiring. 2. 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. 3. All file config I/O swallows errors; a broken store must not break the page. 4. 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. ## Limits - Cards show tokens and wall times, not $ — DSH does not report message cost today. If providers expose usage cost later, it drops into the same fold. - The grid 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 — deliberately deferred. ## Verify bash 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. ## License MIT. Idea and page design derive from ray062/opencode-obvious-grid (MIT).