d0ublecl1ck/dsh-scratchpad-plus

dsh-scratchpad-plus

Workspace-free free chat for DeepSeek Harness. Start a conversation without picking a project directory: a button beside the sidebar's new-session button opens a shared scratchpad workspace, every tool stays available, and sessions that produce real files are automatically promoted into isolated sibling project workspaces with a new-session handoff.

This is a maintained fork. It is based on 1264459640/dsh-scratchpad (MIT), which has had no commits since 2026-08-30 and no longer works on current DeepSeek Harness. The upstream copyright notice is preserved in LICENSE.

What this fork changes (relative to upstream 0.3.0)

Everything else - the promotion pipeline, the commands, the configuration - is upstream's work, unchanged.

When you need it

• You want to try a prompt or prototype a script without deciding which project directory it belongs to, and without littering the sidebar with one-off folders.
• You are mid-conversation and the agent needs to write a real file - you do not want that file to land in a production checkout. Free chats live in a shared scratchpad; anything worth keeping is promoted into its own workspace.
• You keep several throwaway conversations open at once and want them in one place instead of mixed into your project list.

What it does

Requirements

• DSH with the web profile (the host half injects workspaceRegistry from @deepseek-ai/dsh-workspace, webServer, commands, fs, timer, sessions, sessionQuery, agents - all shipped in the web profile's base/web-app bundles; no extra composition rows needed).
• Dependencies: zod and @deepseek-ai/schemastery (declared in package.json).
• The client half starts sessions through uiWorkspace.startSession and falls back to workspaces.startSession on harnesses that still expose the capability there. When neither exists the click reports the missing capability instead of silently doing nothing.
• Checked against the published @deepseek-ai/dsh-client-ui-workspace 0.1.7-rc.2 and 0.2.1-alpha.1, and @deepseek-ai/dsh-client-ui-primitives 0.1.7-rc.2.

Install

# from the npm registry
dsh plugin --profile web add -w dsh-scratchpad-plus

# from a source checkout (development)
dsh plugin --profile web add -w link:/abs/path/to/dsh-scratchpad-plus

Then restart dsh web or the DSH Desktop app. The 「自由对话」 button appears next to the sidebar's 新会话 button; collapse the sidebar for a single icon button between the new-session and workspace icons.

Coming from the upstream package

dsh plugin --profile web remove @banana-peeljj12/dsh-scratchpad
dsh plugin --profile web add -w dsh-scratchpad-plus

Install only one of the two: both register the same loader row id (scratchpad) and the same /scratchpad route prefix. Your data is untouched - this fork uses the same ${DSH_HOME:-~/.dsh}/scratchpad and projects directories, and existing scratchpad workspaces keep working.

Configuration

In the web profile's cordis.patch.yml (or by merging this package's cordis.patch.yml):

- insert:
    - id: scratchpad
      name: 'dsh-scratchpad-plus'
      config:
        scratchpadPath: ''   # default ${DSH_HOME:-~/.dsh}/scratchpad
        projectsPath: ''     # default ${DSH_HOME:-~/.dsh}/projects
        autoPromote: true    # false: only the manual command stays active
        slugMaxLen: 8

Path rules enforced at load:

• ~ expands to the user home; $DSH_HOME (when set) replaces ~/.dsh.
• canonical projectsPath must not equal or nest inside canonical scratchpadPath - the plugin throws a clear config error otherwise (the isolation invariant is the point).

Commands

Troubleshooting

• The sidebar entry is missing. Check the row is composed (dsh --profile web --dump-config | grep scratchpad), then reload the window (Cmd+R). A crashed entry logs slot entry crashed in 'sidebar.footer.action' in the browser console - that is what an icon rename looks like.
• Clicking does nothing. Look for no startSession capability in the browser console: the harness exposes neither uiWorkspace.startSession nor workspaces.startSession. On a harness this fork has not seen yet, please open an issue with the DSH version.
• Sessions pile up without content. Blank sessions are created by the host and are only visible while they are the current one; that is shell behaviour, not this plugin's.

Why promote to a new session (not redirect)

A DSH session's cwd is fixed in its immutable SessionHeader, and workspace membership is derived from that canonical cwd (attachSession validates realpath(header.cwd) === workspace.path). There is no API to move a live session to another workspace. Promotion therefore:

1. mkdir the projects root and atomically claim a unique <date>-<slug>[-N] directory (mkdir({recursive:false}) + EEXIST retry);
2. copy the session's file-set in under a staging temp dir, then rename into place (projects/<slug>/artifacts/), preserving each file's path relative to the scratchpad root (so scratchpad/src/a.go lands at artifacts/src/a.go - no basename flattening, no collisions between same-named files in different subdirs); a half-copied project never reaches the registry (copy failure rolls the whole claimed dir back);
3. workspaceRegistry.create(projectDir, title) - only after the directory exists (the registry realpaths the path);
4. the client banner hands off to a new session in that workspace.

The scratchpad session stays put; originals remain in the shared scratchpad (copy semantics) and can be cleaned with /scratchpad-tidy.

Safety

• Copy, never move. Promotion copies the session's file-set out; originals stay in the scratchpad until you run /scratchpad-tidy --apply, which itself only lists files that no other live scratchpad session still references.
• No tool stripping. The plugin does not narrow what the agent may do; DSH's own sandbox and approval settings remain in charge.
• Nothing is deleted on uninstall. Removing the plugin removes its routes, commands and listeners; registered workspaces and their files stay put.
• No outbound calls of its own. The host half only talks to the harness (registry, web server, sessions) and the local filesystem.

Development

npm ci
npm test                      # all suites
node test/open-session-test.mjs   # client half: starters, icons, placement

The client half is a hand-written, zero-build browser bundle (lib/client.js, window.__ModuleLoader__.load + react/jsx-runtime + dsh-client-ui-primitives) registered through the public slot system - no build step. npm test is expected to be green on Linux and macOS, with or without an ambient DSH_HOME.

Maintainer-side manual checks live in docs/manual-verification.md.

Reproducible render check (needs a running instance and Google Chrome):

DSH_HOME=~/.dsh node scripts/verify-render.mjs                       # dsh web on :3080
DSH_HOME="$HOME/Library/Application Support/dsh-desktop/harness" \
  node scripts/verify-render.mjs --host 127.0.0.1:43129              # DSH Desktop

It navigates headlessly, asserts that the host node is injected directly after the shell's new-session button, that the two share a row with comparable widths, and that no slot entry crashed.

Design notes

• Paired entry via anchor + portal (reviewed DOM injection) - the slot system has no sidebar-section slot, so the client keeps a display:none anchor inside its sidebar.footer.action registration, resolves the sidebar root through an explicit per-step criteria chain (closest('[data-slot="sidebar.footer.action"]') -> footerActions -> footArea -> root), and inserts a flex:none host div directly after the shell's new-session button. CSS :has(> .sp_pairHost) turns the sidebar column into a two-column grid for exactly those two children - the React-owned button is never reparented. createPortal renders into the host, so locales and contexts keep working. Every failed criterion degrades visibly: paired -> full-width section before the workspaces region -> footer button. The host carries a data mark for idempotent reuse and an owner token so unmount/HMR cleanup never leaves residue.
• Slot-only UI, zero shadowing - sidebar.footer.action and conversation.input.dock are additive list slots; the plugin registers nothing into sidebar.workspaces/sidebar.settings (both single) and so cannot shadow core UI or other plugins; unloads cleanly (every host registration is a fiber effect).
• Theme tokens only - all colors are --dsw-alias-* variables; light/dark follows the shell for free (color-scheme).
• Copy, never move - the scratchpad is shared across sessions; moving files would break other live sessions' tool paths. Originals stay until a user-confirmed /scratchpad-tidy --apply.
• Rollback-safe promotion - staging temp dir + rename publishes the project only when complete; registry-create failure rolls the claimed dir back; a new workspace is never registered pointing at a half-copied dir.

Rollback / uninstall

Remove the plugin row (or dsh plugin --profile web remove dsh-scratchpad-plus) and restart. All host registrations (routes, commands, listeners) are fiber effects and disappear; the registered workspaces stay usable as ordinary workspaces, and no physical files are deleted.

License

MIT. Forked from 1264459640/dsh-scratchpad; see LICENSE for both copyright notices.