dsh-custom-js

dsh plugin --profile web add dsh-custom-js

<p align="center">

<img src="./assets/icon.svg" width="96" height="96" alt="dsh-custom-js icon">

</p>

<h1 align="center">dsh-custom-js</h1>

<p align="center">

<a href="https://www.npmjs.com/package/dsh-custom-js"><img src="https://img.shields.io/npm/v/dsh-custom-js.svg" alt="npm version"></a>

<a href="https://www.npmjs.com/package/dsh-custom-js"><img src="https://img.shields.io/npm/dm/dsh-custom-js.svg" alt="npm downloads"></a>

<a href="https://github.com/jeffreyren1/dsh-custom-js/actions/workflows/ci.yml"><img src="https://github.com/jeffreyren1/dsh-custom-js/actions/workflows/ci.yml/badge.svg" alt="CI"></a>

<a href="https://github.com/jeffreyren1/dsh-custom-js"><img src="https://img.shields.io/github/stars/jeffreyren1/dsh-custom-js?style=flat" alt="GitHub stars"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>

</p>

<p align="center"><strong>English</strong> | <a href="README.zh.md">中文</a></p>

dsh-custom-js loads trusted .js, .mjs, and .ts userscripts into the DeepSeek Harness Web GUI. It includes a built-in script manager, hot reload, per-script enable/disable controls, lifecycle cleanup, TypeScript transpilation, runtime status, and bilingual UI copy through the native DSH locale service.

The plugin stays generic. UI changes such as custom Settings layouts, Sidebar buttons, shortcuts, or page behavior live in your own userscripts.

English Version · Chinese Version

 · 

Install

dsh plugin --profile <profile> add dsh-custom-js

Example:

dsh plugin --profile web add dsh-custom-js

Restart DSH after the first installation. Then open Settings → General → Custom JavaScript / TypeScript.

Current package compatibility: DSH >=0.2.0-rc.1 <0.3.0-0, covering 0.2.0-rc.1 and later 0.2.x prerelease and stable versions, using a profile based on the web template.

Update

dsh plugin --profile web update dsh-custom-js

Restart the active DSH process after updating, then refresh the browser page.

Uninstall

dsh plugin --profile web remove dsh-custom-js

Restart the active DSH process after removal. Uninstalling the plugin does not delete $DSH_HOME/custom-js/ or the userscripts stored there. Remove that directory manually only if you no longer need its contents.

Quick start

Open Settings → General → Custom JavaScript / TypeScript, create hello.js, and paste:

console.log('Hello from dsh-custom-js')

Save the script. With auto reload enabled, the Host detects the change and the Client loads it immediately.

You can also create the same file directly at $DSH_HOME/custom-js/hello.js with your preferred editor.

What you can build

Use userscripts to customize the DSH Web GUI, add shortcuts and helper controls, keep reusable debugging tools, or maintain your own small UI extensions without modifying the DSH installation.

More screenshots

Find and replace in the built-in editor

Find or replace code without leaving the DSH Settings page.

Build new DSH features with your own script

This outline view was implemented in a user-written JavaScript file and loaded through dsh-custom-js.

Features

• JavaScript, MJS, and TypeScript userscripts
• Built-in CodeMirror editor with JavaScript / TypeScript syntax highlighting, line numbers, bracket matching, and history
• Ctrl/Cmd+S, Tab indentation, find and replace, and code outline navigation
• Safe-by-default import: new imported scripts remain disabled until you review and enable them
• Export, delete, per-script enable/disable, and contextual retry after runtime errors
• Script-directory path copy and safe folder opening
• File watcher plus low-frequency polling for reliable external-editor updates
• TypeScript ES2022 Module transpilation with compile diagnostics
• Managed default / apply / init lifecycle and cleanup
• Revision protection against overwriting external file changes
• Per-script runtime status
• window.dshCustomJs browser API
• Chinese and English UI through @deepseek-ai/dsh-client-locale

Security

[!WARNING]

Only load code that you wrote yourself or fully trust.

Userscripts run with the browser-side permissions of the current DSH page. They can read and modify the DOM, use localStorage and sessionStorage, access data visible to the page, and make network requests through APIs such as fetch and WebSocket. dsh-custom-js does not sandbox userscripts.

Host management and script routes pass through the DSH Connection request fence, but an authorized userscript still has the browser privileges described above.

Recovery

If a userscript prevents the DSH Web GUI from working:

1. Stop the active DSH process.

2. Open $DSH_HOME/custom-js/ (normally ~/.dsh/custom-js/).

3. Rename the offending file, for example from outline.js to outline.js.disabled.

4. Start DSH again and refresh the browser page.

Only top-level .js, .mjs, and .ts files are loaded, so the renamed file is ignored while its contents remain available for inspection and repair. If you configured a different scriptDirectory, use that directory instead.

Script directory

Default:

$DSH_HOME/custom-js/

If DSH_HOME is unset, the Host uses ~/.dsh/custom-js/. The directory is created automatically.

custom-js/
├─ base.ts
├─ sidebar.js
├─ settings-window.js
└─ shortcuts.mjs

Only top-level .js, .mjs, and .ts files are scanned. Subdirectories and other extensions are ignored. scriptDirectory is relative to $DSH_HOME; absolute paths and .. escapes are rejected.

Script manager

Open **Settings → G

…(truncated)