DeepSeek Harness session and workspace manager —— Workspaces: archive and visibility. Sessions: move, migrate presets, delete, favorite, review later, prioritize, tag, and annotate. Batch operations.
Install
# from npm (prebuilt)
dsh plugin --profile web add dsh-session-manager
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:hkkz9522/dsh-session-manager
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
English | 中文
0 Overview
DeepSeek Harness session and workspace manager —— Workspaces: archive and visibility. Sessions: move, migrate presets, delete, favorite, review later, prioritize, tag, and annotate. Batch operations.
The Web UI and Desktop app share the same plugin Host/client functionality; environment-specific installation notes are documented below.
1 Features
1.1 Session lifecycle management
- Delete is irreversible and always asks for confirmation. Deleting a parent session also deletes its descendant subagent sessions.
- Deletion waits for Agent shutdown and pending session writes. A failure or timeout stops further deletion and reports any partial completion.
- Projection cache cleanup: session deletion also removes its checkpoint and retained legacy cache entry, including cascaded subagents and batch deletion. Delayed writes from the deleted lifecycle are blocked. Cleanup failures are reported as warnings; they do not undo session deletion. The configured DSH home may be a junction or symbolic link; links inside cache paths remain restricted.
- Archive / Unarchive moves a session in and out of the active list while retaining its conversation history. Associated Git worktrees may be cleaned up according to DSH's settings.
- Move to workspace keeps history, title, archive state and derived-session relationships intact, rewrites the session's
cwdto the target workspace, synchronizes the runtimeworkingDirectoryprojection for active agents, and updates the live writer's header in place so any pending tool calls keep landing on the new path. When the session'scwdalready equals the target workspace path but its membership was never recorded, only the missing membership is repaired: nocwdrewrite, no artifact rewrite or move, and no session restart. - Migrate Agent preset rewrites the latest
agent-preset/selectedevent (or the session header if no such event exists) so a session whose preset was renamed or removed can resume. Message history is never altered. - The preset dialog opens with its choices ready. The action button indicates preparation; click it again to cancel. Preparation failures appear in the panel and can be retried.
- Git Worktree: cross-workspace moves are refused when a session has a recorded Worktree association or uses a Git indirection directory. Archiving follows DSH's Worktree cleanup settings. Deleting a session does not remove project directories, Git worktrees, or branches.
1.2 Session shortcuts
- Favorites / Review-later are manual flags that survive archive and session end; neither is cleared automatically.
- Search matches title, session ID, note and tags case-insensitively, trims whitespace, and never reads chat history.
- Filters and sorting combine a workspace selector (All / Ungrouped / specific) with an archive filter (All / Active / Archived), then layer favorites / review, tag and priority filters on top. Sort by recently updated (default), least recently updated, newest created, oldest created, name ascending (A-Z), name descending (Z-A), or priority (1 → 5).
- Priority is a dropdown 1 Highest, 2 High, 3 Normal, 4 Low, 5 Lowest, default 3 (Normal); legacy
nullpriorities are normalized to 3. - Tags / Notes: up to 20 tags per session (≤ 32 characters each) and a 2000-character note. Both English
,and Chinese,are separators, whitespace is trimmed, duplicate tags are merged case-insensitively. - AI-assisted tagging is manual and opt-in: Copy Prompt writes a structured prompt (Chinese or English, matched to the active UI) to the clipboard; Import parses the clipboard JSON (tolerating Markdown fences, conversational wrappers, smart quotes, stray backslashes and a leading BOM), validates it against the same limits, and populates the editor fields. Neither button calls a model automatically.
- Annotations live in plain text under the DSH home (
dsh-session-manager/annotations.v1.json), keyed by session ID. Same-origin client instances stay in sync viaBroadcastChannel. Saves are durable across crashes; revision conflicts surface a "load latest" prompt.
1.3 Bulk management
- Batch process mode: click the toggle in the panel header to reveal row checkboxes, a Select all in filter / Clear selection toolbar pair, and the bulk action bar. Exiting batch process clears the current selection.
- Action bar lists every batch action:
- Annotation toggles: Archive / Unarchive / Favorite / Unfavorite / Mark for review / Clear review flag.
- Mutating actions: Add tags / Clear tags / Set priority / Move to workspace / Migrate preset / Delete session.
- Confirmation flow:
- Non-destructive actions (archive / unarchive / favorite / unfavorite / review / unreview / add-tags / clear-tags / set-priority / move / preset-migrate) fire immediately and report per-session results in a result dialog with Success / Failed / Skipped groups and a one-click Retry failed that re-arms the failed IDs into the selection.
- Destructive actions (delete session) first open a preview dialog listing the targeted sessions, then show a progress bar, then a per-id result dialog.
1.4 Plugin updates and settings
- Self-update check: An npm icon button in the panel header checks for updates and displays a notification dot when a new version is available. One-click updates use DSH's native update operation when available, with a fallback for older hosts. Install-source protection, registry selection, persistent status, post-install checks, and restart/refresh prompts remain available; failures report rollback or manual recovery status.
- Settings Card: Registered under DSH Settings (
settings.plugin.item). Displays current version, latest version, inline check/update buttons, an auto-check toggle, and GitHub repository link. - Install Source (Registry): Select between npm official registry (
registry.npmjs.org, default) and China mainland mirror (registry.npmmirror.com) in the Settings Card. Check for updates and download packages directly from the selected registry. - Dialog opacity: A 50%–100% slider (5% steps, default 100%) with a "Reset to default" button in the Settings Card's preferences section. Adjusts the background fill opacity of plugin dialogs in real time while keeping text, buttons, inputs, tags, and borders fully opaque.
- Theme: Automatically follows the active DSH theme (including third-party theme plugins). Dialogs, settings cards, title-bar buttons, menus, inputs, and all other UI elements seamlessly adapt to light and dark themes.
- Unified dropdown styling: All select dropdowns (sort, filter, priority) use rounded, shadow-free menus matching the active theme. Menus match the trigger width within the visible viewport, choose an opening direction based on available space, and close when zoom, panning, or the soft keyboard changes that viewport.
1.5 Workspace Archiving and Management
- Two-page tab switching: Seamlessly switch between "Session Management" and "Workspace Management" in the dialog header, preserving each page's distinct search, filter, and sort states.
- Workspace list: Displays all registered workspaces with title/name, physical path, session count, latest activity timestamp computed from member sessions, and right-side toggle switch.
- Search, filter, and sort: Case-insensitive search across name and path; filter by All / Active / Archived; sort by Recently Updated, Earliest Updated, Name A-Z, or Name Z-A; counter display and adaptive toolbar wrapping.
- Toggle switch and archiving:
- Turn OFF (Archive): Pre-checks session activity (rejects safely if any session is running), cascades archiving to all unarchived member sessions, hides workspace from DSH native sidebar, and automatically rolls back if partial failure occurs.
- Turn ON (Restore): Removes archive mark, restores workspace in native sidebar, unarchives member sessions previously archived by the workspace operation while keeping individually archived sessions intact. Creating an identical-path workspace restores visibility automatically.
- Native sidebar hiding without ungrouped spill: Employs derived snapshot interception with session ID unioning into
archivedSessionIdsso hidden workspace sessions never spill into "Ungrouped", supporting dark/light themes and persistent recovery across DSH restarts.
2 UI entry points
2.1 Title bar
The right side of the title area exposes actions for the current session: Archive / Unarchive, Favorites, Review-later, Tags / Notes, Move to workspace, Delete session, and More actions (⋯), matching native DSH title-bar button sizing (28px height, transparent ghost style) and vector SVG icon design.
2.2 Sessions and workspaces management entry and interface
Open Sessions & Workspaces from the bottom of DSH's sidebar to browse all sessions and workspaces. Click a session title to open it; there is no separate Open button. Row actions, including Migrate preset, use icons with hover descriptions and accessible labels. The session tab supports switching workspaces, searching by title / ID / notes / tags, filtering, and sorting; the workspace tab supports searching, sorting, bulk actions, and visibility toggling.
2.3 Bulk management
The Batch process button in the session manager panel header is the entry point: click it once to enter batch process (row checkboxes appear, the Select all in filter / Clear selection pair and the bulk action bar show up); click it again to exit batch process.
2.4 Settings Card
Navigate to DSH Settings -> Plugins -> Session Manager to inspect versions, switch between npm official and China mainland mirror registries, toggle auto-update checks, or trigger updates.
3 Installation
3.1 Install from Plugins
In DSH, open Plugins, add a plugin, search for dsh-session-manager, and install it. This method is supported by both the official Web UI and Desktop app.
3.2 Install from Third-Party Plugin Markets
This plugin is listed in dsh-market and awesome-dsh-plugin.
3.3 Install to the Web profile via CLI
Install from npm:
dsh plugin --profile web add npm:dsh-session-manager
Install from GitHub:
dsh plugin --profile web add github:hkkz9522/dsh-session-manager
Restart DSH Web after installation. If the browser still loads an older client bundle, use Ctrl+Shift+R to force-refresh the page.
The
desktopprofile is managed by the official Desktop app and is not intended to be modified with the regulardshCLI. Desktop users should install the plugin through Plugins in the app.
3.4 Local Development / Testing
Web profile
Install the local repository via CLI:
dsh plugin --profile web add <path-to-this-repository>
The local repository is linked to the current profile as a plugin checkout, making it suitable for modifying the source code directly and testing changes.
Desktop app
Open Plugins in the official Desktop app and use the absolute path to the local repository as the installation source.
For client-side code, changes can be reloaded automatically after saving when HMR is working normally. If a change does not take effect immediately, reload the current interface or restart the corresponding DSH Web / Desktop client.
After changing plugin dependencies, package.json, bundle configuration, or other installation- or loading-related settings, reinstalling the plugin or restarting the corresponding client is recommended.
4 Safety and behavior
- Deletion is permanent, so the UI always asks for confirmation. The API checks the session ID, directory boundary and artifact header before deletion; traversal, symlinks and junctions are refused.
- Move and preset migration keep the live session / agent alive; only deletion cancels and disposes the session. Move updates the stored
cwdand the existing live writer's header. - The management list hides subagent sessions and the move API rejects them. Blank sessions without a persisted artifact cannot be moved.
- Cold rewrites preserve the artifact's stored format (V1 / V2 / V3 / V4 are all readable; the plugin never forces an upgrade). Moves and rewrites refuse corrupt / truncated Zstd logs or JSONL logs with incomplete final lines instead of publishing partial history.
- Preset migration separates backup, publication and rollback. If rollback fails, recovery files are retained and their paths are included in the error; do not remove them.
- Workspace archiving rollback protection: archiving is refused if active sessions are present, and batch session archiving automatically rolls back on partial failures to preserve state consistency.
- On startup, sessions whose
cwdnames a registered workspace but whose membership record is missing are re-registered through the official DSH API (idempotent). Incomplete scans skip pruning only: existing membership is never dropped, and live sessions or memberships added during the scan are always preserved. - Plugin mutations are serialized per session and request bodies are limited to 64 KiB. This queue supplements, rather than replaces, DSH's own persistence coordination.
- Centralized API authentication: All
/session-manager/api/*routes are protected by DSH officialconnection.admit()andrequestRejection()gates, strictly enforcing Owner-only privileges (peer.principal.kind === "owner") and failing closed (HTTP 503) if connection services are absent, ensuring that exposed network tunnels or local proxies cannot bypass access control.
5 Compatibility
The table below lists compatible version combinations between DeepSeek Harness (DSH) and dsh-session-manager.
| DeepSeek Harness (DSH) | dsh-session-manager | Environment |
|---|---|---|
| v0.2.2-rc.3 | 0.7.7 |
Desktop |
| v0.2.2-rc.1 | 0.7.6 |
Desktop |
| v0.2.1-rc.2 | 0.7.5, 0.7.4, 0.7.3, 0.7.2 |
Desktop |
| v0.2.0-rc.2 | 0.7.1, 0.7.0, 0.6.4, 0.6.3, 0.6.2, 0.5.4 |
Desktop |
| v0.1.7-rc.2 | 0.5.3 |
Desktop / Web UI |
| v0.1.7-rc.1 | 0.5.2 |
Desktop / Web UI |
| v0.1.6-alpha.2 | 0.5.1 |
Web UI |
| v0.1.5-rc.2 | 0.4.11 |
Web UI |
| v0.1.5-rc.1 | 0.4.10, 0.4.9, 0.4.7 |
Web UI |
| v0.1.3-alpha.2 | 0.4.6, 0.4.4, 0.4.1 |
Web UI |
| v0.1.2-rc.1 | 0.4.0 |
Web UI |
| v0.1.0-rc.7 | 0.1.2, 0.1.1, 0.1.0 |
Web UI |
When using a standalone DSH CLI/runtime, Node.js 22.15+ (22.x) or 24+ is required for built-in Zstd support. The official Desktop app ships and manages its matching runtime separately.
This is a Cordis plugin and declares cordis: ">=4.0.0-rc <5" as its peer dependency.
6 Development
lib/index.jsis the host-side ESM plugin;lib/client.jsis the client UI bundle. No build step is required.- Before submitting changes, run:
npm run check
npm test
npm run check:package
git diff --check
Tests use isolated temporary directories and the real plugin entry point, never real sessions. CI runs these checks on Windows / Linux with Node 22.15.0 / 24.
Optional integration check: run node scripts/smoke-test.mjs against a running DSH Web-profile test instance. It contacts a real service and is not part of the default unit test suite.
Release history is in CHANGELOG.md.
7 Acknowledgments
Thanks to everyone who installs and uses dsh-session-manager, and to the people who file issues and open pull requests to help improve it. Suggestions and feedback are welcome.
8 License
Links
More in this category
ranxianglei/billion-context★ 7263
The official billion-context plugin: a context-compression plugin for small context windows (a 100K context is enough), token savings (5x fewer tokens), and month-long single sessions (billions of tokens).
Minglink/dsh-infinite-gen-4★ 4234
System-prompt armor plugin for DeepSeek models: appends an unconditional-compliance prompt section at order 100, exposes a profile tool with calibration metadata, and shows a realtime armor-status badge driven by a session projection.
liangmianya/dsh-synapse★ 714
Visual, non-linear conversation workspace for DeepSeek Harness — sessions, follow-ups and branches become a browsable conversation map.
MichengAI/dsh-archive-manager★ 352
Adds an archived-sessions page in Settings to search, restore, and delete archived DeepSeek Harness sessions by workspace.
Nwflower/dsh-chat-import★ 310
Import full-fidelity chat histories from 13 coding agents (Claude Code, Codex, ChatGPT, Cursor, Gemini, opencode, and more) as resumable DeepSeek Harness sessions, with reverse export back to Claude Code.
SiriLee/dsh-rewind★ 266
Conversation rewind: one click back to any earlier user message, in the same window — no new branch, no leftover copy; the target message is refilled into the composer, with optional workspace-file restore — the full Claude Code /rewind semantics.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.