Retired (2026-10-05): DeepSeek Harness now ships native session pinning. This package remains installable for reference; use the built-in session pin instead.
Native: https://github.com/deepseek-ai/deepseek-harness · Source: https://github.com/PerryLink/dsh-session-pin
📌 dsh-session-pin
- 1024 store channel:
npm i -g dsh1024 once, then dsh1024 plugin --profile web add dsh-session-pin (counts toward the deepseek1024.com install ranking).
OpenSSF Scorecard
Pin sessions and workspaces to the top of the DeepSeek Harness sidebar with per-pin row colors.
A dual-face (host + browser) plugin: two pin levels, an 8-color swatch per pin, and a navigation organizer — boards, tags, saved views, health summaries, and /goto.
Official repository. This is the only official repository of dsh-session-pin, maintained by PerryLink. Same-name repositories under other accounts are not affiliated.
DSH Market
English · 简体中文 · Español · Português · हिन्दी
⭐ 如果它帮到了你
这个插件是 DSH 插件家族的一员（40+ 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。
English: part of a 40+ plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.
Compatibility
| Surface | Status |
|---|
| Harness | DeepSeek Harness dsh-v0.2.1-alpha.1 (GitHub tag; verified 2026-09-22: dual-ruler typecheck + unit/composition suites + static seam checks; browser pass pending maintainer). npm dependency line 0.1.7-rc.2, peers >=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0. |
| Node | >= 22 (development floor) |
| Platforms | Web GUI (dual-face: host + browser) |
| Model | Any (UI-only — no model traffic, no session events) |
session/pin events | Pre-flight-gated: written only when the host's runtime event vocabulary knows the type (the alpha-line append can no longer stamp the ignorable marker, so the vocabulary is the single gate signal — adapted 2026-09-18); otherwise the projection degrades to the settings cache and one warning fires before the first write. |
What you get
dsh-session-pin keeps the conversations that matter at the top of the sidebar and colors them so you can find them at a glance:
- Two pin levels — pin whole workspaces and individual sessions; a pinned workspace moves to the front of the workspace list and a pinned session to the front of its account.
- Per-pin row colors — a swatch after each pin cycles an 8-color preset palette (Shift+click clears); the row gets a left accent bar plus a translucent tint.
- Four pin surfaces — a hover
[pin][swatch] pair on every row, a pin toggle in the session header, a sidebar foot action with a pinned panel, and per-browser durable pinning that keeps pins and colors across restarts.
- Click-to-open — clicking a pinned row in the sidebar or the pinned panel opens the session in the current window (the same seam
/goto uses); both navigate through the host's session-retain channel on the alpha line.
- Zero core changes — a standalone plugin for the stock DSH Web GUI; every surface degrades gracefully on older baselines.
┌─ Workspaces ────────────────────────────┐
│ 🎨 Workbench ███ │ ← pinned workspace, tinted red
│ 📌 Implement login flow 3h │ ← pinned session, tinted teal
│ Fix the auth bug 1h │ ← hover shows a gray pin + swatch
│ Refactor the DB layer 2d │
└─────────────────────────────────────────┘
Navigation organizer
Four browser-local capabilities organize multi-session work on top of pinning. All state rides the same session-pin store (per-browser; nothing is uploaded), and each has a Config switch.
- Boards — pins join named groups; the board chip row creates, renames, and deletes boards and drag-reorders them (order persists per-browser), while the pinned panel groups each board's pins under a collapsible header.
- Tags & views — entities carry up to 8 tags (≤24 chars each), set per row from the panel's manage button (which also assigns the pin's board); the filter bar matches text and tags, and any filter state saves as a named view (up to 20) for one-click switching.
- Health summary — each pinned session row appends a read-only, sanitized line (
N msgs · you|ai · relative time) derived from the public session snapshot — counts and directions only, never content.
/goto <keyword> — a composer line starting with /goto plus Enter jumps: a unique title/tag match opens it, several matches list in a prompt, none explains. The command line never reaches the model.
How it works
- Host half (
src/index.ts) — declares the session-pin settings form as the plugin's own live Config: the two pinned id lists, the two color maps, the organizer state, and the host policy (maxPins/reorderOnLoad/pruneStale plus the five feature switches) are all .volatile() fields. On the 0.1.7 settings contract a form's namespace is the local id of its profile entry, so the bundle patch's id: session-pin row names the form, the Plugins page edits it, and accepted edits are hot-applied to the running plugin; no session events, no model traffic.
- Browser half (
src/client.ts) — assembles a framework-free PinStore (the host half's live Config form read through ctx.configForms.get(entryId), degrading to a versioned localStorage document with cross-tab sync), a PinController (two-level toggle / color cycle / prune / reorder state machine), and the UI: the row overlay, the optional row-slot registration, the header toggle, the sidebar foot action, and the pinned panel. Ordering goes through ctx.workspaces.
- Log-backed write channel — on builds mounting the built-in
dsh-session-pin service, every session toggle commits through the session.setPinned RPC first (the session/pin event log is the canonical residence) and mirrors the commit into the settings store; a failed or slow RPC degrades to a direct settings write.
- Log-backed projection read —
enableLogBacking (host Config, fail-closed default off) mounts a projection reader that folds live session/pin events into the canonical pin set and mirrors the folded pinned/colors into the live Config, which becomes the idempotent cache for the log-backed state. The event schema, the pure fold (foldPinEvents), and the pre-flight-gated append seam (PinLogAppender) live in src/pin-log.ts: the host's runtime event vocabulary alone gates the write BEFORE the first append (the alpha-line append can no longer stamp the ignorable marker, so the old marker probe is gone), so hosts that cannot safely carry the event — a vocabulary that does not know the type fails closed on read — never receive one; the live Config/localStorage store remains the compat + degradation path.
- Client seam — the browser half reads
SessionId/WorkspaceId brands from @deepseek-ai/dsh-client-connection (the removed package no longer exists on current hosts); the session-header slot's standard-kit seats are typed as a local structural contract. On hosts the row slot is not declared, so session rows fall back to the DOM overlay and the row-slot registration stays deferred.
Extension points used: settings (host); sessions, workspaces, configForms, connection, slots (client); locale (client, optional); conversation.session.header.actions, sidebar.footer.action, shell.overlay, and the upstream sessions.row.action row slot when declared (0.1.2-rc.1 hosts do not declare it — the DOM overlay covers session rows there). Model-visible effects: none — this is a UI-only plugin: it adds no session events and no tokens to any model request.
Quick start
# 1. install the bundle into your profile
dsh plugin --profile web add "github:PerryLink/dsh-session-pin#main"
# or from npm (published releases)
dsh plugin --profile web add dsh-session-pin
# 2. restart and verify the row
dsh --profile web --dump-config | grep -A3 'id: session-pin'
Loader entry id. On harness builds whose dsh-base bundle mounts the built-in host service @deepseek-ai/dsh-session-pin (entry id session-pin), give this plugin a distinct entry id such as id: session-pin-ui in the profile patch row — a duplicate session-pin id fails the boot with "duplicate loader entry id".
Install & uninstall
- git channel (latest
main): dsh plugin --profile web add "github:PerryLink/dsh-session-pin#main" — pnpm run build emits the host half (lib/index.js) and the browser half (lib/client.js).
- npm channel (published releases):
dsh plugin --profile web add dsh-session-pin.
- tarball channel:
pnpm pack in this repo, then dsh plugin --profile web add ./dsh-session-pin-<version>.tgz.
- uninstall:
dsh plugin --profile web remove dsh-session-pin (or remove the row from the profile patch — the row IS the settings form namespace, so removing it also removes the stored form values).
Configuration
All tunables are Schemastery Config fields. Every field below is .volatile(), so it is editable live from the profile's Plugins page as well as from cordis.yml (an accepted edit is committed into the running plugin without a remount); pin lists, color maps, and organizer state are the same kind of field, which is what makes the browser half's store durable. enableLogBacking is deliberately NOT volatile: it was never part of the editable surface and no browser half reads it. cordis.patch.yml mounts the bundle with the defaults below.
| Key | Default | Meaning |
|---|
maxPins | 0 | Maximum pinned entities per level (sessions and workspaces each have their own budget); 0 = unlimited |
reorderOnLoad | true | Re-assert the pinned prefixes (newest pin first) once the lists are ready |
pruneStale | true | Drop pins and colors for entities absent from a ready list (deleted/archived) |
enableBoards | true | Enable pin groups (boards) in the sidebar panel |
enableTags | true | Enable session/workspace tags and the panel filter bar |
enableViews | true | Enable saved filter views |
enableHealth | true | Enable the per-pinned-session health summary (read-only, sanitized) |
enableGoto | true | Enable the /goto <keyword> composer command |
enableLogBacking | false | Fold session/pin events into a log-backed projection and mirror it into the settings cache (fail-closed: the session log is canonical when enabled) |
Tools & surfaces
| Surface | Kind | Notes |
|---|
[pin][swatch] row controls | UI slot / DOM overlay | Hover controls on every session and workspace row |
| Session header toggle | UI slot | The same pin control in the header action row, keyed by session id |
| Sidebar foot + pinned panel | UI slot / overlay | Lists pinned workspaces and sessions, grouped by board (collapsible) with per-row board/tag manage and color dots |
/goto <keyword> | command | Composer quick-jump by title/tag; the line never reaches the model |
session-pin settings form | host service | The plugin's own live Config, durable per profile: pins, colors, and organizer state |
Permissions & data
- Permissions: the
dshWorkshop manifest declares browser:local-storage, settings:read, and settings:write.
- Data: pins, colors, and organizer state live in the plugin's
session-pin settings form (the pinned/workspacePinned/colors/workspaceColors/boards/tags/views volatile Config fields), degrading to a versioned localStorage document (v1 documents migrate) where the web proxy does not serve the entry. Nothing is uploaded. With enableLogBacking, the live Config becomes the idempotent cache for the log-backed session/pin projection.
- Session log: none by default — this plugin adds no session events and no tokens to any model request. When
enableLogBacking is on, the host folds the log-only session/pin event (written by the upstream session.setPinned RPC) into the canonical pin projection; PinLogAppender pre-flight-gates its own writes on the runtime event vocabulary, so hosts that cannot carry the event never receive one. Model-visible effects remain none.
Security boundaries
- UI-only. No model-visible effects, no network, no subprocesses; every surface degrades gracefully on older baselines.
- Durable, bounded state. Pins and colors are pruned with deleted entities (
pruneStale); maxPins caps the pinned count per level.
- Read-only health. The health summary derives counts and directions from the public session snapshot and writes nothing back.
Known limitations
- Persistence scope — the log-backed canonical residence is opt-in (
enableLogBacking, fail-closed default off) and its live read loop requires builds that emit the session/pin event (the upstream session.setPinned RPC); on baselines without it, pins and colors fall back to the plugin's session-pin settings form, then to browser-local localStorage. On hosts whose event vocabulary does not know the type, the pre-flight gate disables log appends entirely (the fail-closed read path would reject such logs), so the projection degrades to the settings cache there.
- Ordering scope — the pinned position is stable only under Manual order; under Updated order the core's activity promotion re-fronts active sessions, and
reorderOnLoad re-asserts the prefixes on load.
- Remote browsers — settings RPCs are loopback-only on the baseline; remote browsers fall back to browser-local
localStorage.
- Row badge fallback — where the upstream row slot is unavailable, session rows are matched by title text; with duplicate titles the badge shows on every matching row and toggles the first match (cosmetic).
- Row DOM dependency — the overlay relies on the core rows'
role="treeitem" structure and must follow upstream UI changes.
Roadmap
Canonical residence: a log-backed session/pin event + pin projection + write RPC (upstream) — the settings namespace then retires as the durable store and the plugin consumes useProjection('pin'). Landed (P0): the plugin ships the session/pin event schema, the pure projection fold (foldPinEvents), the pre-flight-gated append seam (PinLogAppender), and a host projection reader (enableLogBacking) that folds live session/pin events back into the live Config cache. The live Config/localStorage store remains the compat + degradation path; the log is canonical when enabled.- Self-build write fallback: wire
PinLogAppender to append session/pin events on builds without the upstream session.setPinned RPC, so no-upstream baselines also log canonically.
- Consume the upstream
pin projection (useProjection('pin')) on the client once @deepseek-ai/dsh-session-pin ships in the npm baseline; today the host mirror covers the read path on master builds.
- Right-click / row-menu "Pin" entry (needs a core row-level menu slot; the row badge slot is upstream now).
- A full color-picker popover (custom colors) once the canonical residence exists; today's cycle swatch covers the preset palette.
Development
pnpm install # install dependencies
pnpm run typecheck # tsc --noEmit
pnpm test # vitest unit tests
pnpm run build # dual-half build + client-bundle purity check
node scripts/verify-live.mjs # live check against a running `dsh web` (DSH_CHECKOUT env)
Topics
deepseek-harness, dsh, dsh-plugin, session-pin, pin, workspace
Contributors
- @PerryLink — creator and maintainer: pin UX, durable persistence, workspace ordering, per-pin row colors, the navigation organizer, and the five-language docs.
PerryLink DSH Plugin Family
This project is one of the 45 DeepSeek Harness plugins maintained by PerryLink. If this one helps you, the others likely will too:
| Plugin | One-liner |
|---|
| dsh-auto-review | Second-model auto-review on the approval chain, fail-closed by default |
| dsh-autotier | Automatic strong/cheap model-tier routing with deterministic risk guards and a /tier command |
| dsh-background-agents | Durable background child agents with a Web UI sidebar, messaging and interrupt |
| dsh-budget | Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel. |
| dsh-catalog | DSH Desktop Market standard catalog source for the PerryLink family |
| dsh-cert-mcp | Read-only MCP server exposing the certification registry: grades, snapshots and five-dimension evidence |
| dsh-checkpoint-rewind | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore |
| dsh-claude-move | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |
| dsh-click | Cross-platform native desktop control for DeepSeek Harness — Windows first. |
| dsh-composer-history | Terminal-style input history for the web composer: arrows, Ctrl+R search |
| dsh-data-quality | Dataset quality checks and citation cross-checks (the optional numeric bridge consumed here) |
Install from the DSH Desktop Market
All PerryLink plugins are browsable in the built-in DSH Desktop Market: Market → Sources → add source → paste https://perrylink-dsh-catalog.perrylink.workers.dev/catalog-source.json → select it. Installation still goes through the Market's npm-identity verification and your confirmation.
License
Apache License 2.0 © 2026 dsh-session-pin contributors
