DSH plugin workspace: how DeepSeek Harness groups sessions

A DeepSeek Harness workspace is a persistent record of a user working directory: a stable id built on the canonical path, a display title, and an ordered session ledger of the sessions that belong to it (source). It solves a plain problem: sessions keep piling up, and a workspace is how they get grouped by "which directory you were working in" and are still there next launch. This piece covers what a workspace is, how sessions belong to it, and how plugins use it; how to pick and use one is in how to use workspaces, and the session data model is in sessions, stored and queried.

Why a workspace exists

A session only knows which directory it belongs to, via the cwd in its header, and does not know that "these sessions should be seen together" — the workspace supplies exactly that grouping and persistence (source). Break the problem apart:

1. Sessions get out of hand: one task may open several sessions, and after enough days time-sorting cannot take you back to "what I did in that project last time".
2. The directory is a natural dimension: you already work in project directories, so grouping by directory beats hand-tagging and is harder to forget.
3. The grouping must persist: a temporary grouping is useless if it resets next launch; a workspace writes it into a persistent record, hence "still there after you close it".
4. The grouping must not disturb the model: it is purely an organising device for humans, and putting it into the conversation context would only waste budget.

So a workspace is designed as a host-side optional capability, not part of the agent loop trunk and invisible to the model: it has no tools, no prompt text and no session events.

What a DeepSeek Harness workspace is: one persistent record

A DeepSeek Harness workspace has three parts — a stable id, a display title and an ordered session ledger — and its path is the canonical path resolved at creation, never rewritten afterwards (source). Three points:

1. Stable id: built on the canonical path, it uniquely identifies the workspace inside the system; even if the directory is later moved, this id does not change.
2. Display title: it defaults to the directory name and may repeat; it can be changed to any string. It is a human-facing label and does not carry identity.
3. Ordered session ledger: it records the ids of the sessions that belong to it, in a hand-maintained order — new sessions are prepended and activity does not reorder it.

How a session belongs to a workspace

In DeepSeek Harness, membership requires two conditions at once: the ledger contains the session id and the session header's canonical cwd equals the workspace path (source). From that:

1. Structurally at most one workspace: because both must hold, a session does not fall under two directory names at once.
2. The ledger is the source of truth: membership is not derived from an unvalidated cwd — the ledger is authoritative, and cwd is used only for validation, never to "claim" a session.
3. Joining is explicit: a new session must be explicitly added to belong; a session that already belongs can also be removed from the ledger.
4. Removal does not affect the session: removing it from the ledger only dissolves the grouping; the session's own event log is untouched — grouping and data are two layers.

Why the path is canonical, and what happens if the directory is gone

A DeepSeek Harness workspace records the canonical path resolved at creation and does not rewrite it afterwards — the record keeps the real path resolved at creation even if the directory later disappears (source). This is often misread, so two points:

1. The record does not check whether the directory still exists: judging whether the directory is currently there needs a separate live directory check, not the recorded path; the record itself does not update when the directory vanishes.
2. A stable path makes membership deterministic: precisely because the path is not rewritten once set, the session's cwd comparison has a definite basis; otherwise one directory change would drift every historical membership at once.

How history is seeded: once, on first launch

DeepSeek Harness seeds history only on the first successful startup: sessions whose canonical cwd is valid are grouped by directory with the newest first (source). About that seeding, three points:

1. It happens once: it is a one-off "give old sessions their grouping" action, not a routine rerun on every launch.
2. Historical sessions without a cwd stay ungrouped: without that information membership cannot be validated, so they stay ungrouped — which is normal.
3. Later sessions are added explicitly: sessions created after seeding are not automatically dropped into a workspace; giving one a workspace is an explicit add.

How a plugin uses it: registry and directoryPicker

A DSH plugin uses workspaces through ctx.workspaceRegistry, the registry entry that registers and resolves workspaces and maintains order and the session ledger, while directory selection goes through ctx.directoryPicker, an abstraction seam (source). The two entries divide the work:

1. ctx.workspaceRegistry handles data: creating, resolving and ordering workspaces and operating the session ledger all live here; a plugin reads or writes workspaces through it.
2. ctx.directoryPicker handles interaction: directory selection is made an abstraction seam, so different access paths (graphical UI, scripts) each supply an implementation, letting one set of workspace logic serve several front ends.
3. Both are host-side: neither enters the model-visible context, so more workspaces do not add prompt cost. To organise plugin config by workspace in the UI, look under Settings → Plugin Market, which is DSH Plugin Hub.

How to select a workspace in the interface is in how to use workspaces.

Notes on workspaces

Read a workspace as a "directory + session ledger" binding record and it will not blur with a session.

1. A workspace is not the directory itself: it is a persistent record of the directory, and the record outlives the directory.
2. Membership is ledger plus cwd check: both conditions are required; missing one means it is not a member.
3. The order is manual: activity does not reorder it, and new sessions are prepended.
4. Ungrouped is normal: historical sessions without a cwd belong to no workspace.
5. Deleting a workspace does not touch session logs: sessions return to ungrouped, but the records remain.
6. It is invisible to the model: this capability does not enter the conversation context and costs no prompt budget.
7. For the how-to, see how to use workspaces; the session data model is in sessions, stored and queried.

Source: DeepSeek Harness docs - workspace subsystem, docs - session query.