dsh-folder-launcher

中文 | English

Add any folder to a running DeepSeek Harness Web workspace from the Windows Explorer context menu, and let it start dsh web automatically when needed. A small host plugin plus a per-user Explorer integration; no administrator rights, no restart of the running DSH instance, no editing workspace.json.

• Registers the folder through DSH's own workspaceRegistry, so the Web sidebar receives the workspace normally.
• Works without browser auth cookies: the launcher calls a loopback-only route protected by a local bearer token.
• Windows 7 / 8 / 10 / 11 compatible scripts (PowerShell 2.0 syntax); Windows 11 puts classic verbs under Show more options (Shift+F10 opens the classic menu directly).
• Cross-platform Node CLI for Linux/macOS file managers and scripts.

The DSH host itself requires Node 22; the Explorer scripts are Win7-compatible, but DSH may not run on Windows 7. See requirements.

---

How it works

Explorer right-click
   │  wscript.exe (no console flash)
   ▼
explorer/dsh-folder-launcher.ps1
   │  reads $DSH_HOME/folder-launcher/state.ini + token
   │  POST /dsh-folder-launcher/add  { "path": "..." }
   ▼
dsh-folder-launcher host plugin
   │  bearer token + loopback-only + reject Origin
   │  ctx.workspaceRegistry.create(path)
   ▼
workspace appears in the DSH Web sidebar

Discovery files:

$DSH_HOME/folder-launcher/state.ini   # pid / port / origin / startedAt
$DSH_HOME/folder-launcher/token       # 32-byte random hex token

$DSH_HOME defaults to %USERPROFILE%\.dsh.

---

Install

1. Install the DSH plugin

dsh plugin --profile web add github:snnnnke/dsh-folder-launcher#v0.1.0

No tag yet? Use the default branch:

dsh plugin --profile web add github:snnnnke/dsh-folder-launcher

Local development:

dsh plugin --profile web add file:D:\path\to\dsh-folder-launcher

2. Restart dsh web

Stop the running process (Ctrl+C) and start it again:

dsh web

Verify the plugin published its state:

Get-Content "$env:USERPROFILE\.dsh\folder-launcher\state.ini"

3. Install the Explorer menu

A git clone contains the whole repository: the root has install-context-menu.ps1 and the explorer/ folder. You do not need to find the plugin under %USERPROFILE%\.dsh.

In a normal PowerShell (not elevated):

git clone https://github.com/snnnnke/dsh-folder-launcher.git
cd dsh-folder-launcher
powershell -ExecutionPolicy Bypass -File .\install-context-menu.ps1

cd dsh-folder-launcher enters the clone you just created — not the plugin installation directory. If you cloned somewhere else, cd there or use the full path:

powershell -ExecutionPolicy Bypass -File "C:\your-clone\dsh-folder-launcher\install-context-menu.ps1"

install-context-menu.ps1 is a root-level entry that calls explorer\install.ps1; running .\explorer\install.ps1 directly is equivalent. The root entry just makes “clone, then install” obvious.

Do not run it elevated: the menu is per-user and is written to HKCU. Running as administrator writes to the administrator's account instead.

The installer writes only:

• HKCU\Software\Classes\Directory\shell\DshFolderLauncher
• HKCU\Software\Classes\Directory\Background\shell\DshFolderLauncher
• HKCU\Software\Classes\Drive\shell\DshFolderLauncher
• %LOCALAPPDATA%\dsh-folder-launcher\

No HKLM, no admin.

The repository root is the DSH plugin; explorer/ is the menu installer. dsh plugin add github:... installs only the plugin, never the menu. For the menu, clone or download the ZIP and run install-context-menu.ps1 from the repository root. The installer copies the scripts it needs to %LOCALAPPDATA%\dsh-folder-launcher; the clone can then be deleted or moved.

ZIP users: GitHub → Code → Download ZIP → extract → run install-context-menu.ps1 in the extracted folder.

To simulate a network pull with a local bare repository (run in a normal PowerShell, not the DSH sandbox):

cd D:\Code_stuff\harness_work
git clone --bare --branch main .\create .\gh-sim\dsh-folder-launcher.git
git clone --branch main .\gh-sim\dsh-folder-launcher.git .\pull-test\dsh-folder-launcher
cd .\pull-test\dsh-folder-launcher
powershell -ExecutionPolicy Bypass -File .\install-context-menu.ps1

4. Use it

Right-click a folder, folder background, or drive → Add to DSH Web.

If DSH Web is not running, the launcher starts dsh web directly (no confirmation) and returns immediately; a hidden background worker performs the add once the plugin is ready. DSH can take a minute or two to start with a heavy profile, so the Explorer action does not block. Toggle with StartWebIfMissing in %LOCALAPPDATA%\dsh-folder-launcher\config.ps1.

---

Windows 11

Classic registry verbs appear under Show more options. Press Shift+F10 for the classic menu directly. A true top-level Windows 11 menu needs a packaged IExplorerCommand COM server (MSIX sparse package, signing/developer mode); not included.

---

No terminal DSH / CLI

DSH core has no official interactive terminal UI (TUI):

• The installed DSH ships a web profile; headless is a one-shot task, not an interactive terminal.
• There is no @deepseek-ai/dsh-tui on npm; dsh tui requires a separately installed third-party or custom profile.
• The old “Open terminal here” menu item only opened a terminal and never started DSH. It has been removed to avoid the misleading impression.

If you want a terminal UI, install a third-party TUI yourself and run it in a terminal; this project does not bundle or install one.

Cross-platform CLI

node .\bin\dsh-folder-launcher.mjs add "D:\Code\my project"
node .\bin\dsh-folder-launcher.mjs health
node .\bin\dsh-folder-launcher.mjs state

On Linux/macOS, wire it into a file-manager custom action, for example:

node /path/to/dsh-folder-launcher/bin/dsh-folder-launcher.mjs add %f

---

Security

The local route is outside DSH's browser /api fence and owns its own checks:

1. Loopback only — 127.0.0.0/8, ::1, or an IPv4-mapped loopback address.
2. Bearer token — persistent token in $DSH_HOME/folder-launcher/token.
3. Origin rejected — any request carrying an Origin header gets 403.
4. Bounded body — 16 KiB, application/json only.
5. Directory validation — absolute, existing directory; the actual registration uses workspaceRegistry (realpath-normalized).

Threat model: browser/CSRF protection, not protection from local malware running as the same user. Keep DSH_HOME and the token private. If DSH uses a self-signed TLS cert, the launcher skips certificate validation only for loopback HTTPS.

If DSH is bound to a non-loopback address with --host, do not call the local route through that LAN address: the route accepts loopback sources only, and a LAN-IP request is refused with 403. The default dsh web bind (127.0.0.1) is the supported setup.

---

Uninstall

powershell -ExecutionPolicy Bypass -File .\explorer\uninstall.ps1
# also remove config/log:
powershell -ExecutionPolicy Bypass -File .\explorer\uninstall.ps1 -RemoveData

dsh plugin --profile web remove dsh-folder-launcher

Restart dsh web afterwards.

---

Development

npm test
powershell -ExecutionPolicy Bypass -File .\scripts\check-scripts.ps1

Tests cover route guards (401/403/404/405/413/415), idempotency, path validation, token comparison, discovery state, plugin apply/cleanup, and a fake-host integration that exercises the real plugin entry over HTTP.

Manual launcher test without a full DSH:

node .\scripts\fake-host.mjs C:\temp\dsh-fake-home 0 C:\temp\marker.txt
# in another normal PowerShell:
$env:DSH_HOME = 'C:\temp\dsh-fake-home'
$env:DSH_FOLDER_LAUNCHER_NO_UI = '1'
powershell -ExecutionPolicy Bypass -File .\explorer\dsh-folder-launcher.ps1 add "D:\some folder"

Real DSH end-to-end should run in a normal terminal (not inside a restricted DSH sandbox), because DSH spawns worker processes during boot.

Architecture: docs/architecture.md. Troubleshooting: docs/troubleshooting.md. Chinese details: README.zh.md.

---

Compatibility

• DSH >=0.2.1-rc.3 <0.3.0-0.
• Windows 7 SP1+ for the Explorer scripts (PowerShell 2.0 syntax); validated for syntax and launcher flow on Windows 11 PowerShell 5.1. Windows 7 behavior should be verified on the target machine.
• Windows 11 top-level menu: not supported.
• Other OSes: plugin + Node CLI work; Explorer registry integration is Windows-only.

License

MIT © 2026 snnnnke