# dsh-gitbash-preset

> Provides a Windows variant for DSH minimalist mode, using Git for Windows MSYS bash instead of standard bash, and fixes compatibility issues on Windows.

## Metadata

- Author: [@liceses](https://github.com/liceses)
- Repo: <https://github.com/liceses/dsh-gitbash-preset.git>
- GitHub: [liceses/dsh-gitbash-preset](https://github.com/liceses/dsh-gitbash-preset)
- Stars: 135
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `dsh`, `dsh-plugin`, `dsh-plugins`
- Forks: 0
- Open Issues: 0
- Last push: 2026-08-16T17:54:06.000Z
- Added: 2026-08-16T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:liceses/dsh-gitbash-preset
```

## Wiki

## One-Line Description
Provides a Windows-compatible variant for DSH minimal mode: redirects bash tool invocations from persistent PTY (which cannot start on Windows) to Git for Windows' bundled bash (MSYS), solving the issue where the official minimal mode fails to run on Windows.

## Core Capabilities
- On startup, copies the bundled "Minimal Mode (Git Bash)" preset to the user preset root directory; skips if already exists to avoid overwriting user files
- Automatically locates Git for Windows bash path: prioritizes `GIT_BASH` environment variable, then scans common installation directories and PATH, and skips Windows' built-in WSL launcher to avoid misuse
- Executes bash commands as `bash -c <command>` by spawning a new shell each time, uniformly handling timeout, background execution, output truncation, and error diagnosis
- Security guaranteed through sandbox policy gating: refuses execution under non-"full-access" sandbox, and prompts to use `sandbox_permissions: "danger-full-access"` for one-time upgrade
- Retains the minimal mode's persona and str_replace_editor tool surface, providing the same user experience as the official minimal mode

## Technical Implementation
- **Language**: JavaScript (ESM, native Node.js)
- **Key Dependencies**: Uses only Node built-in modules (`node:fs` / `node:path` / `node:os` / `node:url`); preset consists of host's existing `@deepseek-ai/dsh-persona` / `dsh-tool-bash` / `dsh-fs-local` / `dsh-tool-str-replace-editor`
- **Architecture Pattern**: Injects plugin via `cordis.patch.yml` into web profile; `apply(ctx, config)` in `lib/index.js` copies preset files to user directory on startup; preset internally uses entry-local realm to register `shell` service and `bash` / `str_replace_editor` tools
- **Entry Files**: `lib/index.js` (installer) + `agent-presets/minimal-gitbash/agent.cordis.yml` (preset composition) + `agent-presets/minimal-gitbash/gitbash-executor.mjs` (bash executor)

## Use Cases
When Windows users use "Minimal Mode" on DSH Web, the persistent bash fails due to PTY limitations and missing bash. This plugin provides a one-click installable alternative preset, enabling Windows to use bash tools in minimal mode just like macOS/Linux.

## Prerequisites and Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DSH | Not declared | Runs via `@deepseek-ai/dsh-*` host package; no version range declared in manifest |
| Node.js | >=20 | From `package.json` `engines.node` |
| Operating System | Windows | Preset is directly disabled with `process.platform !== 'win32'`, only active on Windows; executor falls back to `bash` on non-Windows but preset itself won't activate |
| Git for Windows | Recommended | When not installed, executor falls back to PATH or bare `bash` name, may fail to start |
| Native Modules | None | Uses only Node built-in modules, no npm native dependencies |

## Installation
```bash
dsh plugin --profile web add github:liceses/dsh-gitbash-preset
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `shellPath` | string | Explicitly specify bash.exe path, empty for auto-detection (`GIT_BASH` → common install dirs → PATH) | Auto-detect |
| `timeoutMs` | milliseconds | Default timeout for single command | 120000 |
| `maxTimeoutMs` | milliseconds | Maximum allowed timeout for single command | 600000 |
| `maxOutputBytes` | bytes | Maximum bytes retained per stream (stdout/stderr), overflow written to spill file | 64000 |
| `maxSpillBytes` | bytes | Total size limit for spill files | 67108864 (64MB) |
| `graceMs` | milliseconds | Grace period from SIGTERM to SIGKILL when terminating process | 3000 |
| `force` | boolean | Plugin-level config: whether to overwrite existing preset with bundled files | false |

## FAQ

**Q: Who is this plugin for?**

A: Primarily ordinary Windows users using DSH minimal mode. The official minimal mode doesn't run on Windows, and this plugin provides an alternative preset variant.

**Q: Do macOS or Linux users need to install this?**

A: No. The preset is internally disabled with `process.platform !== 'win32'`, so even if installed on other systems, it won't activate. The official minimal mode will continue to be used.

**Q: What do I need to do after installation?**

A: Restart DSH to let the plugin write the preset to user directory (approx `~/.dsh/.agent-presets/minimal-gitbash/`), then when creating a new session in the Web UI, select "Minimal Mode (Git Bash)".

**Q: Can I use it when the session sandbox is workspace-write?**

A: Not directly. The bash tool will refuse to execute due to sandbox restrictions; either switch the session to "full-access" sandbox mode, or have the model use `sandbox_permissions: "danger-full-access"` with justification for a one-time upgrade as prompted by the error.

**Q: Will it modify the bash tools already on my computer?**

A: No. It only replaces the shell provider within the scope of sessions that select "Minimal Mode (Git Bash)"; other sessions and system bash are completely unaffected.

**Q: How do I force overwrite an already installed preset?**

A: Set `force` to `true` in the plugin configuration. The plugin will overwrite the version in the user directory with the bundled preset files (it won't delete files you added separately).

**Q: How do I uninstall it?**

A: Use `dsh plugin --profile web remove` to remove the plugin, then manually delete the `minimal-gitbash` folder in the user directory.

**Q: What's the difference between this and the official minimal mode?**

A: The persona and str_replace_editor tool surface are completely identical; the only difference is that the bash tool spawns a new shell for each invocation and doesn't preserve `cd` / `export` state. This is a compromise after being unable to use persistent PTY on Windows.

## Difficulty Level
Beginner — Install the plugin, restart DSH, select the preset, and it's ready to use. No code or config changes needed; only advanced users who want to fix the bash path or adjust timeouts need to look at `agent.cordis.yml`.

## Known Issues and Limitations
- When session sandbox is workspace-write or stricter, Git Bash cannot start within Windows restricted token sandbox (MSYS runtime cannot create signal pipe). Need to switch to "full-access" or use one-time upgrade — this is a sandbox boundary, the plugin doesn't bypass it
- Each bash invocation spawns a new shell and does **not** preserve session state like `cd` / `export` (different from official minimal mode's persistent PTY shell). Models need to include full paths in each command or maintain working directory themselves
- Preset is only enabled on Windows platform; even if installed on macOS/Linux, it will be disabled by the `disabled` condition in `agent.cordis.yml`
- Preset disables background tasks (`enableRunInBackground: false`); long-running tasks need to be managed via single command timeouts
- In extreme cases, when both Git Bash and WSL launcher (bash.exe in System32) exist in PATH, the executor actively skips WSL launcher directory to avoid getting a non-existent distribution stub

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-gitbash-preset](https://deepseek-plugin.org/plugins/liceses/dsh-gitbash-preset)
Wiki generated by AI (model: `MiniMax-M2.5`)