BetterShell

Cross-platform persistent shell tools for DeepSeek Shell (DSH).

BetterShell provides two plugins:

• @gao-gao-zai/better-shell-terminal: owner-scoped persistent PTY and single-process service.
• @gao-gao-zai/better-shell-tools: the shell_execute, shell_write, shell_read, and shell_session tools.

Features

• Persistent PTY sessions across tool calls within the same DSH Agent lifecycle.
• Windows profiles: PowerShell 7, Windows PowerShell 5.1, and cmd.exe.
• POSIX profiles: bash (default on Linux/macOS, interactive readline so long command lines never truncate) and sh (single-process only), plus pwsh7 when PowerShell Core is installed.
• Agent-identity isolation for sessions, commands, cursors, and jobs.
• Foreground, background, timeout, cancellation, and completion notifications.
• Encoding-safe bounded output with incremental cursors: PowerShell profiles force UTF-8, cmd follows the system code page (GB18030 on Chinese Windows), POSIX profiles decode UTF-8.
• Process-tree cleanup with abrupt-host-death protection: Windows Job Objects with kill-on-close and fallback termination; POSIX process-group guardians whose watchdog kills the whole group when the DSH host disappears.
• Official DSH settings integration with live resource limits.
• Optional user approval integration for shell commands.
• Environment and working-directory validation, including optional allowedCwdRoots.
• Owner-scoped concurrent job admission and lifecycle cleanup.

Requirements

• Windows 10/11 or Windows Server with the configured shell profiles available, or Linux/macOS with bash (and base64 from coreutils/busybox) installed.
• Node.js 24 or newer.
• pnpm 11 or newer.
• DSH with the compatible @deepseek-ai/* peer dependencies.
• On Linux, node-pty compiles natively at install time: a C/C++ toolchain (gcc/clang, make) and Python 3 are required when no prebuilt binary matches your platform.

POSIX notes: PTY sessions use the bash profile because interactive bash reads through readline (no tty canonical-mode line-length limit); sh is restricted to single-process execution because dash-style shells truncate long interactive input lines. Commands are delivered base64-encoded through the PTY, so the base64 utility must support -d. Very large commands (tens of KB) written to macOS's stock bash 3.2 can hit an upstream readline corruption bug (microsoft/node-pty#833); Linux bash 4/5 is unaffected. Daemon-style commands that call setsid escape process-group cleanup on POSIX, exactly as detached daemons escape the Windows Job Object.

Installation

BetterShell is not yet published to npm. Install it from this repository or from the generated local tarballs.

Build from source

git clone https://github.com/gao-gao-zai/BetterShell.git
cd BetterShell
pnpm install --frozen-lockfile
pnpm build

The build output for each plugin is written to its package lib/ directory.

Install the generated tarballs

The repository build creates the following installable artifacts:

.artifacts/gao-gao-zai-better-shell-terminal-0.2.0.tgz
.artifacts/gao-gao-zai-better-shell-tools-0.2.0.tgz

From the compatible DSH host project, install both packages together:

pnpm add `
  E:\\DeepSeekHarness\\BetterShell\\.artifacts\\gao-gao-zai-better-shell-terminal-0.2.0.tgz `
  E:\\DeepSeekHarness\\BetterShell\\.artifacts\\gao-gao-zai-better-shell-tools-0.2.0.tgz

Load @gao-gao-zai/better-shell-terminal before @gao-gao-zai/better-shell-tools. The terminal plugin provides the betterShell service consumed by the tool plugin. The DSH host must provide compatible @deepseek-ai/* peer dependencies.

At least one configured shell profile must be available on the host: PowerShell 7 (pwsh7), Windows PowerShell, or cmd.exe on Windows; bash (or sh for single-process execution) on Linux/macOS.

Permission behavior

BetterShell follows the DSH host permission mode:

• In workspace-write or read-only, shell session creation and command execution go through DSH approval and can show a Web UI approval prompt.
• In danger-full-access, BetterShell checks the current Agent/session Sandbox mode and executes directly without an approval prompt.
• If the current Sandbox mode cannot be resolved, BetterShell fails closed and keeps using DSH approval.

The danger-full-access exception is deliberately based on the effective Sandbox mode for the current Agent/session, not only the DSH_PERMISSION_MODE environment variable. BetterShell does not redefine DSH's approval.never policy; it treats an explicitly unconfined Sandbox as the host's direct-allow mode while preserving its own Shell profile, cwd, output, timeout, and concurrency limits.

Development

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm test:integration
pnpm build
pnpm check:packages

The integration suite runs on the current platform: the Windows jobs exercise the configured PowerShell and cmd.exe profiles through ConPTY and Job Object cleanup, while the POSIX jobs (Linux/macOS) exercise bash PTY persistence, the base64 command wrapper, Ctrl+C cancellation semantics, and process-group cleanup. The suites for the other platform skip automatically.

Packages

Terminal service

@gao-gao-zai/better-shell-terminal exposes LocalBetterShellService, profile helpers, configuration schemas, and the terminal service types. PTY sessions are scoped by the exact Agent object and are closed when the owner or DSH process is disposed.

The optional allowedCwdRoots terminal configuration restricts session and single-process working directories to existing directories below the configured roots. Without this option, working directories must still be absolute, NUL-free, existing directories.

Tool plugin

@gao-gao-zai/better-shell-tools registers:

• shell_execute: run a single process or execute inside an existing PTY session.
• shell_write: write text or control input to a PTY session.
• shell_read: list commands for a specified session and read full or incremental output.
• shell_session: create, list, delete, and cancel sessions or commands.

Tool responses use structured error objects and bounded JSON output. Background jobs can inject a completion notice into the owning Agent conversation. Whether that notice may wake an idle owner agent is controlled per job with shell_execute's wake_on_completion argument, defaulting to the terminal plugin's completionDelivery setting (quiet, with wakeup opt-in) and bounded by maxConsecutiveWakes. The tools package also bundles a better-shell DSH skill with the exact profile names, parameter contracts, and persistent-session workflow; it is loaded on demand by the DSH skill loader.

Release artifacts

Release tarballs are generated under .artifacts/ by the package checks and publish commands. The packages are intended to be installed into a compatible DSH host rather than run as standalone applications.

License

MIT. See LICENSE.