---

👋 Hi

dsh is open source and built around one idea: everything is a plugin. The core ships the runtime; everything else — commands, web routes, tool gates, auth walls — is a cordis bundle you add to a profile.

dsh-plugins is a community-curated collection of those bundles. Each one lives as its own npm package under plugins/<name>/, installable per-profile:

pnpm dsh plugin --profile my-profile add ./plugins/<name>
pnpm dsh --profile my-profile

No forking the harness. No patching core. Add and go.

📦 Plugins

name	version	status	what it adds
dsh-auth-plugin	0.1.0	🟡 POC	Login overlay for the Web GUI + /login /logout /whoami slash commands + tools/pre-execute permission gate

See each plugin's README.md for install steps, config schema, and known limits.

🚀 Quick start (someone using a plugin)

# 1. Have dsh installed and at least one profile set up.
pnpm dsh --profile demo --help

# 2. Drop in a plugin from this repo:
pnpm dsh plugin --profile demo add ./plugins/auth

# 3. Boot with the new plugin loaded:
pnpm dsh --profile demo

pnpm dsh plugin --profile demo remove dsh-auth-plugin rolls it back.

🧩 Add a plugin (contributor)

Fork the repo, drop your bundle in, open a PR. Full guide in CONTRIBUTING.md; the gist:

mkdir plugins/<your-plugin>
# copy plugins/auth/{package.json,cordis.patch.yml,index.js,README.md} as a template
# rewrite name/id/config, write apply(ctx, config)

Every plugin is independent — no shared state, no central config to update, no central build pipeline to break.

Layout

dsh-plugins/
├── plugins/                  # one subdirectory per plugin (each a separate npm package)
│   └── auth/                 # dsh-auth-plugin
│       ├── cordis.patch.yml  # bundle manifest (id: auth, name: dsh-auth-plugin)
│       ├── index.js          # cordis apply() — host/web side
│       ├── package.json
│       └── README.md
├── AGENTS.md                 # conventions every plugin follows
├── CONTRIBUTING.md           # how to add a plugin here
├── CODE_OF_CONDUCT.md
├── LICENSE                   # MIT
├── SUPPORT.md                # where to ask questions, file issues
├── pnpm-workspace.yaml
├── package.json              # monorepo root: shared scripts (build/lint/test)
├── tsconfig.base.json        # shared TS config (for plugins that adopt TS)
├── .oxlintrc.json            # shared lint rules
└── .editorconfig

Each plugins/<name>/ is a single npm package named dsh-<name> (unscoped — see Naming convention below). Plugin authors add a new sibling directory; nothing else moves.

Install a plugin

From the harness repo, with pnpm dsh wired up:

pnpm dsh plugin --profile <name> add ./plugins/<plugin>
pnpm dsh --profile <name>

pnpm dsh plugin remove <plugin> undoes the install.

Local dev setup

Each plugin declares dsh packages (@deepseek-ai/dsh-commands, …/dsh-tools, etc.) as version-ranged dependencies. A fresh checkout needs them installed:

pnpm install

SSH / GitHub authentication

The repo assumes you can push to git@github.com. On a dual-boot Windows + WSL machine, the SSH keys typically live in WSL (~/.ssh/id_ed25519_*) and OpenSSH on Windows has no key — git push fails with Permission denied (publickey). Sync once:

# from WSL bash
mkdir -p /home/dfy/.ssh-staging
cp ~/.ssh/id_ed25519_* ~/.ssh/known_hosts ~/.ssh/config /home/dfy/.ssh-staging/
cp /home/dfy/.ssh-staging/* /mnt/c/Users/11404/.ssh/
rm -rf /home/dfy/.ssh-staging

(Replace id_ed25519_* with whichever key names you actually have; the config + known_hosts copy is optional but avoids re-prompting on first run.) Then verify from PowerShell:

ssh -T git@github.com
# expect: Hi <user>! You've successfully authenticated, but GitHub does not provide shell access.

Editing

• Windows-native edit + WSL bash for git ops: open files in your normal editor; run git push from a WSL bash (wsl -e bash) where the SSH agent already has the key loaded.
• WSL-only: edit directly in WSL (/home/dfy/workspace/dsh-plugins/); the Windows view at \\wsl$\Ubuntu\home\dfy\workspace\dsh-plugins is the same files.

Source-checkout of dsh itself

The auth plugin reads the SPA dist from apps/web/dist/index.html in a sibling deepseek-harness/ checkout. If your layout differs, set DSH_DIST_PATH or adjust the bundle's dist resolution to match.

⬆ Upstreaming to dsh

dsh itself is still pre-PR-friendly — see CONTRIBUTING.md in the dsh repo (external PRs aren't accepted yet). When they are:

1. Mirror the dsh conventions: packages/<group>/<name>/ (instead of our plugins/<name>/), add tsconfig.json and a build pipeline (tsdown), expose both host (./) and client (./client.js) entries.
2. Tag the GitHub repo with the dsh-plugin topic so the dsh ecosystem catalog picks it up.
3. Open the PR against deepseek-ai/deepseek-harness.

This repo's layout stays compatible: each plugin's files map 1-to-1 onto a future packages/<group>/<name>/ subtree in the dsh monorepo. Moving a plugin upstream is a copy-paste with a config rename, not a rewrite.

🚢 Releasing

Each plugin is published independently to npm. Bump version per package, then:

pnpm -F dsh-<capability>-plugin publish

For coordinated multi-plugin releases, add changesets or release-please — both work with pnpm workspaces out of the box.

🏷 Naming convention

Plugins live as unscoped npm packages named dsh-<capability>-plugin:

field	rule	example
directory	plugins/<short-name>/	plugins/auth/
npm package	dsh-<capability>-plugin	dsh-auth-plugin
patch id	lowercase capability shortname (no dsh- prefix)	auth
patch name	exact npm package name	dsh-auth-plugin

The pattern dsh-<capability>-plugin keeps future plugins in lockstep (dsh-metrics-plugin, dsh-tools-plugin, …) and avoids two npm collisions we already hit (dsh-auth is taken by an unrelated nginx-fronted bundle). The -plugin suffix matches the dsh-plugins collection's identity — the repo is named dsh-plugin, every member is a -plugin package.

💬 Community

• 🐛 Bug in a plugin? Open an issue on the relevant plugin's plugins/<name>/README.md "Known limitations" first; if it's a real bug, file it at Issues.
• 💡 Plugin idea / discussion? GitHub Discussions.
• 🔒 Security issue? See SECURITY.md.
• 📜 Community norms — CODE_OF_CONDUCT.md.

📄 License

MIT per plugin unless noted otherwise.

---

_{Made with 🛡️ by the dsh community. Plugin ideas welcome — see CONTRIBUTING.md.}