---

[!WARNING] This is an unofficial, community project — not a DeepSeek product. dsh-vsc is not affiliated with, endorsed by, or sponsored by DeepSeek or the deepseek-harness team. It is an independent, best-effort VS Code client for the open-source harness.

[!CAUTION] Very early alpha — use entirely at your own risk. This extension starts a local dsh agent server that runs model-driven code. The agent can create, modify, and delete files in your workspace, and it calls the DeepSeek API on your behalf, consuming your tokens and potentially incurring real costs. The software is provided "AS IS" without warranty of any kind, and the authors accept no responsibility for any errors, data loss, or costs arising from its use. Please read the full Disclaimer before using.

---

Table of Contents

• ✨ Features
• ⚠️ Prerequisites
• 🚀 Getting Started
• 🖥️ Usage
• ⚙️ Configuration
• ⌨️ Commands
• 🛠️ Development
• 🧪 Tests
• 🏗️ Architecture
• 🗺️ Status and Roadmap
• 🧩 Known Limitations
• 🤝 Contributing
• 📄 License and Disclaimers

---

✨ Features

• 💬 Native chat panel (webview) with streaming output, tool-call cards, collapsible reasoning, and full Markdown rendering.
• 🧠 Session management — new / fork / rename, a collapsible session rail, model & reasoning-effort switching per session.
• 📝 Editor integration — right-click Ask dsh About Selection, plus Explain / Fix / Generate Tests / Review code actions.
• 📂 Copilot-style file-change rows with +added −deleted diff stats — click a write/edit to open the whole-file diff; reads open the file directly.
• 🛡️ Inline approvals & questions with a permission seat (approval presets) — answer right in the chat composer.
• 🧮 Context meter, per-turn and total token usage stats.
• 🗜️ Compaction UI and slash commands (/compact, /export, /feedback, /goal, /permission, /plan).
• 🔑 API key management from the command palette / status bar, persisted through the dsh server credential store.
• 🚀 Auto-starts the dsh CLI — or connects to a dsh server you are already running.

⚠️ Prerequisites

Requirement	Version	Notes
VS Code	^1.90.0	any recent stable build
Node.js	>= 22	only needed to build from source / run the extension host
dsh CLI	latest	not bundled — install with npm install -g @deepseek-ai/dsh
DeepSeek API key	—	set inside the extension, or via DEEPSEEK_API_KEY in the shell that starts dsh

🚀 Getting Started

1. Install the dsh CLI

The extension does not bundle the CLI — install it first:

npm install -g @deepseek-ai/dsh

Then restart VS Code (or run dsh: Check dsh Installation). The extension will:

1. Locate dsh on your PATH (or the path set in dsh.cliPath);
2. Start the server automatically with dsh --profile web --port 0 and connect;
3. Show a yellow warning in the status bar when the CLI is missing — click it to open an install terminal.

Already running a dsh web server? Set dsh.connectionUrl (e.g. http://127.0.0.1:3080) and the extension connects to it instead of starting its own.

2. Install the extension

Option A — build the VSIX and install it:

npm install
npm run package     # → dsh-vsc-0.1.0.vsix
# VS Code: Extensions → ⋯ → Install from VSIX...

Option B — run from source:

npm install
npm run build
# press F5 to launch the Extension Development Host

3. Quick start

1. Open the chat panel: dsh: Open dsh Chat (Ctrl+Alt+D).
2. Set your API key when prompted, or any time with dsh: Set API Key.
3. Type a message — a new session is created at your workspace root and the agent starts working.

🖥️ Usage

Chat panel

The chat panel is a Copilot-style conversation: streaming assistant output, tool-call cards, collapsible reasoning, context meter, and per-turn token stats. Pending approvals and questions take over the composer so you can respond inline. The session rail on the right shows your history — create, fork, rename, and switch models per session.

Editor integration

Select code and hit dsh: Ask dsh About Selection (Ctrl+Alt+Shift+D) to send it with file context, or use the Explain / Fix / Generate Tests / Review code actions from the editor context menu or lightbulb. When the agent edits files, Copilot-style file-change rows appear in the chat with +added −deleted counts — click one to open the whole-file diff; read calls show a subdued row that opens the file directly.

API key

The DeepSeek API key is stored through the dsh server's credential mechanism (default ~/.dsh/.credentials.yaml, 0600 permissions), matching the Models page of the dsh Web UI. When no key is configured you are prompted once after connecting; you can set or clear it any time with dsh: Set API Key / dsh: Clear API Key. Click the "dsh connected" status bar item to open a menu with settings entries.

If the shell that starts dsh already sets DEEPSEEK_API_KEY, it is treated as a read-only source and the extension's writes are rejected — unset that variable in the shell that starts dsh before saving through the extension.

Keybindings

Action	Windows / Linux	macOS
Open dsh Chat	Ctrl+Alt+D	Cmd+Alt+D
Ask dsh About Selection	Ctrl+Alt+Shift+D	Cmd+Alt+Shift+D

⚙️ Configuration

All settings live under the dsh.* namespace in settings.json (command dsh: Open dsh Settings):

Setting	Default	Description
dsh.cliPath	""	Absolute path to the dsh executable; empty searches PATH
dsh.connectionUrl	""	Connect to a running server; empty starts the CLI automatically
dsh.autoStart	true	Start dsh when the extension activates
dsh.autoConnectWorkspace	true	Create a workspace-rooted session after startup
dsh.cwdStrategy	workspace	Working directory for new sessions: workspace / firstWorkspace / host
dsh.agentPreset	standard	Agent preset for new sessions; standard renders the working directory + loads AGENTS.md, minimal does not
dsh.provider / dsh.model	""	Default provider / model for new sessions (empty = dsh default)
dsh.reasoningEffort	""	Default reasoning effort when the model supports it
dsh.webviewTheme	auto	Chat panel theme: follow VS Code or force light / dark
dsh.autoScrollThreshold	100	Auto-scroll threshold (px from bottom) during streaming
dsh.notifyOnChanges	true	Show a notification when the agent modifies files

⌨️ Commands

Command	Description
dsh: Open dsh Chat	Open the chat panel
dsh: Start dsh / Stop dsh / Restart dsh	Manage the dsh server
dsh: New Session	Create a new session
dsh: Session History	Open the chat panel and browse history
dsh: Select Model	Switch the current session's provider / model / reasoning effort
dsh: Set API Key / Clear API Key	Manage the DeepSeek API key
dsh: Ask dsh About Selection	Send the selection with file context to dsh
dsh: Explain / Fix with dsh / Generate Tests / Review with dsh	Editor right-click / code actions
dsh: Stop Current Response	Cancel the current response
dsh: Check dsh Installation	Check whether the CLI is available
dsh: Install dsh CLI	Run the global install in a terminal
dsh: Open dsh Web UI in Browser	Open the dsh Web UI in the browser
dsh: Open dsh Settings	Open dsh.* settings
dsh: Show dsh Menu	Open the status bar menu

🛠️ Development

npm install
npm run build     # esbuild → out/extension.js + out/webview/app.js
npm run watch     # incremental build
npm test          # vitest (protocol / session fold / pure-function unit tests)
npm run typecheck # tsc --noEmit
npm run lint      # eslint (flat config, recommended rules; see eslint.config.mjs)
npm run package   # vsce package → dsh-vsc-<version>.vsix

Press F5 in VS Code to launch the extension host (requires Node ≥ 22).

🧪 Tests

npm test runs only the unit tests (test/**/*.test.ts) and never requires an API key. Two integration tests against a real dsh server auto-skip when the CLI is absent:

• test/e2e-real-dsh.test.ts — needs a built deepseek-harness CLI; the checkout path comes from the DSH_REPO env var, defaulting to the sibling ../deepseek-harness.
• test/_probe-real-title.test.ts — a manual dev probe (prints traces, asserts nothing), skipped by default; run it explicitly with DSH_PROBE=1: $env:DSH_PROBE=1; npx vitest run _probe-real-title (PowerShell)

🏗️ Architecture

flowchart LR
    subgraph VS Code Extension Host
        WEB[Webview Chat Panel<br/>React 18] -->|request / push| RELAY[Message Relay]
        EDITOR[Editor Integration<br/>Ask / Code Actions / Diff] --> SESS[Session Manager]
        RELAY --> SESS
        SESS --> PROTO[Protocol Client<br/>HTTP RPC + WS Downlink]
    end
    PROTO -->|HTTP / WebSocket| DSH[dsh Server<br/>--profile web]
    DSH --> API[(DeepSeek API)]

• src/shared/ — wire types (envelopes / frames / SessionEvent) shared verbatim by the host and webview; no VS Code dependency.
• src/host/ — CLI location, spawn, URL parsing, process lifecycle; the HostManager connection state machine.
• src/protocol/ — HTTP RPC client, dual WS downlink streams, reconnect, typed API.
• src/sessions/ — session-list cache, per-session event window (seq dedup / history paging / full-page replace), pending approvals/questions.
• src/webview/ — WebviewView provider and message relay (request/response correlation + push dispatch).
• src/editor/ — selection → context prompt, code actions, file snapshots and diff.
• src/settings/ — dsh.* config reads, session cwd strategy.
• src/install/ — CLI detection, status-bar indicator, install prompt.
• webview/ — React 18 front end: folds events into a render model (turn/step grouping, chunk accumulation, tool-call pairing).

🗺️ Status and Roadmap

Current state: early alpha. The core loop — chat, sessions, model switching, editor integration, approvals, and diff — works end to end against a real dsh server.

Planned / not yet ported:

• Image attachments (paste / drag / lightbox + session.attachment upload)
• Reference chips / @-mentions in the composer
• Plan-mode toggle
• Marketplace publishing and prebuilt VSIX releases

🧩 Known Limitations

• Very early alpha — expect bugs, rough edges, breaking changes, and missing features at any time.
• Windows is the primary test platform; macOS / Linux are not yet verified.
• The extension drives a real agent — see the Disclaimers.

🤝 Contributing

Contributions are welcome! This is a community project, so PRs, issues, and ideas all help.

• Report bugs and request features via GitHub Issues.
• Open a pull request with your changes.
• Before submitting a PR, run the checks: npm run typecheck && npm run lint && npm test && npm run build.
• Keep changes focused; add or update tests alongside behavior changes.
• Be kind and constructive — follow a standard open-source code of conduct.

📄 License and Disclaimers

License: MIT. Copyright © 2026 the dsh-vsc contributors.

Unofficial status: dsh-vsc is an unofficial, community-maintained extension. It is not affiliated with, endorsed by, or sponsored by DeepSeek or the deepseek-harness project. "DeepSeek", "DeepSeek Harness", and "dsh" are trademarks or names of their respective owners and are used here only to describe compatibility.

No warranty / liability: the software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in contract, tort, or otherwise, arising from, out of, or in connection with the software or its use. You are responsible for what the agent does in your workspace and for the API usage (and cost) it incurs.

🔗 Related

• dsh-vsc — this repository
• DeepSeek Harness (dsh) — the agent harness this extension talks to
• DeepSeek API — API keys and billing