Preface¶

DSH’s sidebar comes with an archive, but there is no entry to truly delete sessions: to get rid of a mistakenly opened session, you can only let it linger in the archive and continue occupying disk space. Deleting a workspace is cleaner; sessions on disk remain unaffected, only the cwd no longer matches any registered workspace, so the sidebar doesn’t even list it. When there are many workspaces, the sidebar is also a long strip of flat items without grouping.

dsh-session-hygiene is the plugin to fill these three gaps. It is maintained by liudapeng0311, categorized under admin-security, has 0 stars on the community directory, its functionality is not indicative of maturity and has not been widely verified, and the source code is straightforward to read.

What is this¶

One-sentence positioning: adds three things to DSH’s session lifecycle—recoverable deletion, orphan session cleanup, and workspace categorization. The author emphasizes in the README that the plugin has an incremental nature: it does not replace or hide any built-in rows, nor does it rewrite DOM outside these components, and after uninstallation, the sidebar returns to the shell’s original rendering state.

The three trigger points fall on:

• The session row’s ... menu: adds Delete session (to trash).
• Settings → Session cleanup: scans for orphan sessions, supports archiving, moving to trash, restoring, and permanent deletion.
• Settings → Workspace categories: creates categories, displays grouping headers in the sidebar, and supports drag-and-drop assignment and collapsing.

Core Features¶

Delete session to trash, instead of unlinking directly¶

Hover the mouse over a session in the sidebar, open the ... menu, and select Delete session (to trash). The session row disappears immediately, but the data is merely moved.

The underlying steps in order are: stop the currently running task and hide the row first, then unbind the session ID from all workspaces and unpin it, then rename the entire <home>/sessions/<group>/<id>/ directory and move it into the trash, while recording a preview and using api-session/removed to let opened pages drop this row without a refresh. The projection cache is retained, so the restored session can still display the original title and opening hint.

If the move reports “the session data is still in use”, it means another view is occupying this directory; switch to another session and try again. When the move fails, the archive rolls back, and the session is displayed as-is.

Clean orphaned sessions left by deleted workspaces¶

Open Settings → Session cleanup; it scans when the page loads, and Rescan can be used to rescan.

The definition of Orphaned sessions is: a stored session where header.cwd does not match any registered workspace. Each row displays the title, opening preview, original workspace, directory name, and size. There are three ways to handle them:

• Line-by-line Move to trash.
• Batch Archive N: move them into the shell’s archive, skipping subagent sessions (which are usually held by the parent session).
• Batch Move all to trash: includes subagent sessions and will require double confirmation.

There is another type of Detached session: the cwd matches a workspace that exists, but that workspace does not list this session, so the sidebar groups them under Ungrouped. They are displayed in a strip above the tabs, offering Attach all, which is more convenient and safer than moving them to the trash—the sessions themselves are healthy.

Trash: Restore or Permanently Delete¶

The Trash tab lists the content moved in:

• Restore renames the directory back to the recorded path and remounts it to the workspace owning that cwd. If the original path is occupied, it returns a 409 denial; you must move or delete the occupant first. If the original workspace no longer exists, the session returns in an ungrouped state because no workspace claims its cwd.
• Delete permanently unlinks the directory and drops the projection cache entry. This is the only irreversible operation; the interface specifies exactly what is being deleted and requires another confirmation click.

Workspace Categories¶

Open Settings → Workspace categories:

• Add category, which can be renamed inline, reordered using ↑/↓, and Delete removes the category, automatically moving its associated workspaces back to unclassified.
• Assign a category to a workspace via the dropdown or by dragging the workspace row to a category title in the sidebar.
• Save and regroup writes the assignment results and reorders the workspace registry so that rows for each category appear contiguously, with unclassified workspaces at the end. Built-in drag-and-drop sorting still works; the plugin only reorders when saving.
• Clear assignments returns all workspaces to unclassified but does not delete the category itself.
• Click the title to collapse/expand a category; the collapsed state is remembered. The Show category headers in the sidebar toggle allows you to hide the grouping strip without canceling the assignment.

A category only shows its title when its rows form a continuous block; when they are split, it prefers not to show a title rather than placing it above rows belonging to other categories. The grouping strip is a node attached by the plugin itself, and the sidebar is fully restored after the plugin is removed.

Installation and Enablement¶

The plugin is published on the npm registry and can be installed via the DSH Plugins page or via the agent:

plugin_manager install_bundle dsh-session-hygiene

If installing a local checkout, pass its absolute path:

plugin_manager install_bundle <path to this checkout>

The host-side JavaScript does not hot reload; you must restart the host after installation. Uninstalling simply removes the bundle from the DSH Plugins page, and the sidebar grouping strip disappears immediately.

A practical reminder: before uninstalling, please empty or restore the trash first. After the plugin is removed, the <home>/storages/session-hygiene/ directory remains on disk, but sessions in the trash have no UI to restore; you can only manually rename the directory back using their respective entry.json.

Typical Usage¶

Below is a walkthrough of the most common cleanup flow following the path in the README.

1. Delete mistakenly opened session, then regret it¶

Find the session in the sidebar → ... menu → Delete session (to trash) → Open Settings → Session cleanup → Trash tab → Select the row → Restore.

2. Clean up large amount of orphaned sessions left by deleted workspaces¶

First go to Settings → Session cleanup to check the Orphaned sessions list and confirm it’s not a misjudgment (see known limitations below), then select batch Archive N. If you confirm you won’t use them again, select Move all to trash and follow the double confirmation prompts. Subagent sessions should be kept outside the archive as they are part of the parent session.

3. Categorize workspaces by project¶

Settings → Workspace categories → Add category → Use the workspace row dropdown or sidebar drag-and-drop to assign → Save and regroup. Later, the sidebar will show grouping strips with titles, and you can click the title to collapse them.

Where the Data Lives¶

The plugin writes only to one location, <home>/storages/session-hygiene/:

<home>/storages/session-hygiene/
  categories.json
  trash/<sessionId>__<stamp>/
    entry.json
    session.v4.jsonl.zstd ...

entry.json records sessionId, cwd, from (original directory), title, preview, createdAt, sizeBytes, and deletedAt. This is the only file created by the plugin itself and is the source of its restore capability. To manually empty the trash, delete this directory tree. The projection cache is a byproduct; it is intentionally retained when moving to the trash and cleared together only during permanent deletion.

Applicable Scenarios and Notes¶

Suitable for those who use workspaces as projects in DSH, have hundreds of sessions, want to handle the sessions left behind when deleting a workspace, and hope for a safety net when deleting.

A few points to note:

• The plugin runs with the permissions of the current dsh process; read the source code and license before installing and enabling. This plugin is under the MIT license; the repository address is at the end of the article.
• Known limitations: the orphan judgment compares header.cwd with the directory recorded in the workspace registry; sessions where the directory has been renamed on disk will be misjudged as orphans. When deleting a workspace, it still does not warn in advance how many sessions there are; the plugin only lists them in Settings afterwards, because intercepting the built-in delete flow would require taking over the sidebar.workspaces slot which is the shell’s sole single slot. Subagent sessions are marked separately and do not go into Archive N, but they do go into the bulk trash. Category title display depends on rows being continuous; inserting a row in the middle of a single-category row will guess based on the title above, which may not be accurate. Host-side JavaScript does not hot reload; you must restart after installing or updating.
• This plugin is a third-party package on the community directory (standalone site) and has no official affiliation with DeepSeek / Huafan.

Conclusion¶

dsh-session-hygiene focuses on three things: turning deletion into a recoverable move, exposing orphan sessions left by deleted workspaces, and adding grouping to the sidebar. These are all additions and do not change built-in behavior. If you are troubled by a pile of sessions and scattered workspaces, it is worth trying; if you just want to look at the implementation, the entry.json field design and the slot table in the README are quite clear.

• Directory page: https://www.skillhub.cn/plugins/liudapeng0311/dsh-session-hygiene
• GitHub: https://github.com/liudapeng0311/dsh-session-hygiene