dsh-wsl-first
English | 中文
Make DSH reach for WSL first on Windows.
🎯 Have WSL installed? Then use it — don't let the agent default to writing PowerShell.
Why
On Windows, DSH hands the model pwsh as its default command tool. There's nothing wrong with that in itself, but if the machine already has WSL, that default costs you.
Models write bash more naturally than PowerShell. Their command instincts are POSIX-shaped. Forcing a switch to PowerShell means translating pipes, quoting, and paths back and forth — and every mistranslation is a retry. Every retry is tokens burned for nothing.
Output is the same story. Linux commands tend to print tight, plain text. PowerShell hands you tables and object properties by default, and the same information takes visibly more room.
Paths too. The WSL tool converts C:\... to /mnt/c/... on its own, so the model never has to think about it.
So this plugin does one small thing: it adds a section to the system prompt saying to try wsl first. It grants no capability and disables no tool — it just changes the default order.
That prompt text only lists tools that are actually registered. If a tool isn't installed, it won't appear there, which means the model never gets told to call something that doesn't exist. A static instruction file can't do this; it just repeats what you wrote.
Features
- 🚀 Saves tokens | One less syntax translation means one less retry |
- 🔧 Configurable | Prefer bash instead, or name only
wsl — it's a config change , Only advertises tools that are actually registered |
Requirements
- | DSH |
>=0.1.7-rc.2 |
- | Required plugin | dsh-wsl-tool — provides
wsl / wsl-path / wsl-env / wsl-doctor |
- | WSL | WSL2, at least one registered distribution,
wsl.exe on PATH |
- | Platform | Recommend Windows First|
This plugin registers no tools of its own — it only routes between tools other plugins provide. Without dsh-wsl-tool there is no wsl to prefer, and the section renders empty.
Install
npm install dsh-wsl-first
Then add it to your profile's package.json:
{
"dsh": {
"profile": {
"bundles": ["...", "dsh-wsl-first"]
}
}
}
The bundle ships its own cordis.patch.yml, which inserts the routing row process-wide — every agent preset gets the section without declaring anything. A profile restart is required; the loader reads its composition at startup.
If the wsl tool itself isn't installed yet, get that first:
npm install dsh-wsl-tool
DSH version compatibility
package.json declares engines.dsh: ">=0.1.7-rc.2".
The plugin declares no @deepseek-ai/* peer dependency and imports none of their values. That's deliberate: at startup DSH runs evaluatePluginCompatibility over every profile bundle, and if even one peer range fails to cover the running version, the whole bundle is skipped — cordis.patch.yml never takes effect, and it looks like "installed but nothing happens". With no peer range to check, that particular failure can't happen here.
If the plugin goes quiet after a DSH major upgrade, check stderr for skipping profile bundle and confirm engines.dsh still covers your version.
Configuration
Every field is optional and settable in a profile patch (- id: wsl-first-routing / config:) or by environment variable. Precedence: row config > environment > built-in default.
| Field | Default | Environment | Meaning |
|---|
preferred | wsl | DSH_WSL_FIRST_PREFERRED | The tool to try first |
alternatives | ['bash'] | DSH_WSL_FIRST_ALTERNATIVES | Tried after the preferred one (comma-separated) |
discouraged | ['pwsh'] | DSH_WSL_FIRST_DISCOURAGED | Pushed to last resort (comma-separated) |
promptPolicy | true | — | Publish the section at all |
sectionOrder | 3260 | — | The section's sort order |
sectionName | dsh-wsl-first:shell-routing | — | The section's stable name |
extraGuidance | '' | — | Extra text appended to the section |
labels | built-in | — | {tool: task description} rows for the table |
requirePreferred | false | — | Only publish while preferred is visible |
WSL only, nothing else
- id: wsl-first-routing
config:
preferred: wsl
alternatives: []
discouraged: []
The section then names wsl alone, and doesn't appear at all where wsl isn't installed.
Prefer bash instead
- id: wsl-first-routing
config:
preferred: bash
alternatives: []
discouraged: []
wsl is only the default — the plugin is a general executor router.
Configuration rules
A tool that is both an executor and a last resort is a contradiction, and it throws rather than letting a silent winner decide. Repeating preferred among alternatives is not a contradiction — it's just redundant (it happens naturally when you point preferred at bash), so it gets de-duplicated.
The rendered prompt
# Shell routing: wsl first
**For every command execution, call `wsl` as the first and default tool.**
| Task | Tool |
| --- | --- |
| Any command, build, git, pipeline, script, file listing, search | `wsl` |
| Windows-native only: registry, services, COM, cmdlets with no Linux equivalent | `pwsh` (last resort) |
## Rules
- `wsl` is the primary command executor. Reach for it first, every time.
- Use `pwsh` **only** when the task genuinely requires functionality no other available tool provides — and say why in the same reply.
- Never use `pwsh` merely because it appears first in a tool list, and never as a fallback when a `wsl` command fails: fix the command and retry there.
- Do not mix shell syntaxes. A `wsl` call contains the syntax of the shell that tool runs; each executor has its own quoting and path rules.
- `wsl` paths are Linux paths (`/mnt/c/...`). Windows paths in `command`/`workdir` are translated automatically; pass `translatePaths: false` to hand a native path to a Windows program.
That block is the real output, read back from a live session's system prompt. Note there's no bash row in it: the profile it came from had no bash tool registered, so the router dropped it.
Project layout
dsh-wsl-first
├── index.js # Host half: registers the systemPrompt section
├── lib/
│ ├── config.js # Config resolution, precedence, validation
│ └── policy.js # Tier ordering and prompt rendering
├── test/
│ ├── smoke.mjs # Config and rendering (27 checks)
│ ├── mount.mjs # Real apply() mount (8 checks)
│ └── docs.mjs # Both READMEs quote the real render (3 checks)
├── cordis.patch.yml # Bundle layer: inserts the routing row process-wide
├── dsh-plugin.json # Plugin manifest
└── package.json
Tests
npm test
Both modules under lib/ are pure, so the tests need no DSH host. mount.mjs runs the real apply from index.js against a fake cordis context and asserts the registered section's name, order and rendered text. docs.mjs re-renders the section and compares it byte for byte against the block quoted in each README, so the documented output cannot drift from what the code emits.
License
MIT
