dsh-plugin-gitbash

dsh-plugin-gitbash

Run commands on the Windows host's Git for Windows Bash from
DeepSeek Harness (DSH).

A self-contained zero-dependency Cordis plugin that registers one model tool,
gitbash. Typical use cases:

• Running git for Windows-native repositories (git from git-bash, not WSL).
• Executing Windows executables, cmd/PowerShell-free scripting, native
  Windows paths (D:\..., C:\...) while the harness runs under WSL.
• Anything that must touch the Windows side of a dual-boot / WSL setup,
  without leaving the agent session.

中文说明

How it works

Each call spawns a fresh Git Bash process:

<bash.exe> -c '<command>'

with stdin: 'ignore' (fd 0 on /dev/null), so the shell always runs
non-interactively and exits instead of hanging. No state (cwd, env vars,
shell functions) persists between calls.

Path semantics inside command: the spawned executable is the Windows
Git Bash, so use git-bash/Windows paths (/d/tools, D:/tools, C:\...).
WSL /mnt/... paths are not valid inside the command.

Workdir semantics: a workdir argument (or the session workspace, used
by default) is mapped for the spawning layer — /mnt/X/..., /X/... and
X:\... forms all become /mnt/X/..., which WSL interop converts into the
native Windows directory. An unmappable WSL-only path (e.g. /home/...)
starts in the session working directory (reported as //wsl.localhost/...
under WSL interop) instead of failing the call.

Requirements

• A DSH profile running on:
  • WSL / Linux with Git for Windows installed on a mounted Windows drive, or
  • native Windows with Git for Windows installed.
• The harness host must reach the bash.exe (see resolution below).

Installation

From npm (once published)

dsh plugin --profile <name> add dsh-plugin-gitbash

dsh plugin installs the package into the profile and — because the package
declares dsh.bundle — automatically appends it to the profile's bundle
stack (dsh.profile.bundles). Restart the profile (dsh web / dsh --profile <name>) to mount the gitbash tool.

From GitHub (before npm publishing)

dsh plugin --profile <name> add https://github.com/<owner>/dsh-plugin-gitbash

or pin an immutable commit for reviewable installs (recommended for
production):

dsh plugin --profile <name> add https://github.com/<owner>/dsh-plugin-gitbash#<commit-sha>

Manual bundle edit

Add the dependency to the profile's package.json dependencies, append
dsh-plugin-gitbash to dsh.profile.bundles, then run
dsh plugin --profile <name> install.

Agent preset row (drop-in file)

The plugin intentionally imports nothing beyond the Node builtin node:fs,
so it also works as a relative row file inside an agent preset composition —
no package install needed. Copy lib/index.js into your preset directory and
add:

# agent.cordis.yml
- id: tool-gitbash
  name: ./index.js   # or ./gitbash.mjs — your copied file

Verification

node test/smoke.mjs

Runs the real plugin against the machine's actual Git Bash and prints
SMOKE: ALL PASS; skips gracefully (exit 0) where no git-bash exists.

Configuration

Table row config for the bundle row (or your preset row):

Key	Type	Default	Meaning
gitBashPath	string	—	Explicit path to bash.exe. Trusted as-is, no detection.
autoDetect	boolean	true	Search well-known install locations when no explicit path is set.
timeoutMs	number	120000	Default per-call timeout; a single call can override with its timeoutMs argument.
maxOutputChars	number	65536	Tail-truncate captured stdout/stderr to this many characters per stream (the full capture still exists in the collector/spill).

Resolution order: config.gitBashPath → DSH_GITBASH_PATH env var →
auto-detection (unless autoDetect: false). Self-healing: when no path
resolves at mount time, every call re-runs the resolution — installing Git
for Windows or mounting a drive takes effect without a DSH restart.

Auto-detection candidates:

• Windows host: %ProgramFiles%\Git\bin\bash.exe,
  %ProgramFiles(x86)%\Git\bin\bash.exe, then bash via PATH.
• WSL / POSIX: /mnt/<c..z>/Program Files/Git/bin/bash.exe and the
  (x86) variant (checks every mounted drive letter).

Example — explicit path as row config:

- id: tool-gitbash
  name: 'dsh-plugin-gitbash'
  config:
    gitBashPath: '/mnt/e/Program Files/Git/bin/bash.exe'

No time to edit config? Set the environment variable:

export DSH_GITBASH_PATH='/mnt/e/Program Files/Git/bin/bash.exe'

Troubleshooting

• No Git for Windows bash.exe found / Git Bash not found at ... —
  install Git for Windows, make sure the drive is mounted, then set
  gitBashPath or DSH_GITBASH_PATH.
• Command hangs / never returns — git-bash runs with stdin from
  /dev/null, so interactive prompts cannot block it by design; a genuinely
  long command just needs a larger timeoutMs. It is always killable.
• workdir ignored — a WSL-only path (e.g. /home/...) cannot be a
  Windows process cwd; the call starts in the session working directory and
  the note explains it. Use /mnt/X/..., /X/... or X:\... forms to
  control it.
• WSL path errors inside the command — inside command you are in
  Windows git-bash: use /d/..., D:/..., never /mnt/d/....
• State lost between calls — by design every call is a fresh process;
  chain commands in one call (cd /d/tools && git status) when you need
  state.

Layout

lib/index.js        the Cordis plugin (zero runtime dependencies)
cordis.patch.yml    dsh.bundle patch — inserts the tool row
dsh.plugin.json     DSH plugin manifest (tool discovery metadata)
README.md / README.zh.md  bilingual docs
test/smoke.mjs      standalone smoke test (Linux + Windows CI)
.github/workflows   CI: Linux syntax/branch tests + Windows real git-bash run

License

MIT — see LICENSE.