ccch1mneyyy/dsh-TUI / guide/dsh-tui-guide
dsh-tui-guide
UnverifiedUse when the user asks about dsh-tui itself (usage, shortcuts, config, themes, migration, VS Code). Load before answering; skip for normal coding tasks.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.3 KB |
| claude-backend.en.md | markdown | 14.5 KB |
| claude-backend.md | markdown | 13.2 KB |
| cli.en.md | markdown | 9.0 KB |
| cli.md | markdown | 8.4 KB |
| codex-backend.en.md | markdown | 23.3 KB |
| codex-backend.md | markdown | 20.7 KB |
| configuration.en.md | markdown | 43.0 KB |
| configuration.md | markdown | 39.4 KB |
| getting-started.en.md | markdown | 30.9 KB |
| getting-started.md | markdown | 28.9 KB |
| interaction.en.md | markdown | 75.1 KB |
| interaction.md | markdown | 68.8 KB |
| migrate.en.md | markdown | 10.5 KB |
| migrate.md | markdown | 9.5 KB |
| plugins.en.md | markdown | 16.8 KB |
| plugins.md | markdown | 14.5 KB |
| themes.en.md | markdown | 10.3 KB |
| themes.md | markdown | 10.0 KB |
| user-guide.en.md | markdown | 80.9 KB |
| user-guide.md | markdown | 75.0 KB |
| vscode.en.md | markdown | 13.8 KB |
| vscode.md | markdown | 12.6 KB |
vscode.en.md
View on GitHub# Using dsh-TUI in VS Code
[Documentation index](README.md) · [中文](vscode.md)
dsh-TUI is a terminal program: it writes ANSI into a PTY and reads keys
back from the PTY. So any compatible terminal can host it — including the
**VS Code integrated terminal** (xterm.js). This page covers two ways to
use it:
**The `dsh-tui-vscode` companion extension (recommended)**
- sessions run in a real VS Code integrated terminal (a new column beside
the editor);
- multiple concurrent sessions, a sidebar session history, one-click start;
- resume-last and specific-session resume;
- published on the VS Code Marketplace.
**Run directly in the built-in terminal**
- zero install, seconds to start;
- for when you do not want the extension.
> Version note: `dsh-tui` here means this repository (the TUI plugin);
> `dsh-tui-vscode` means the companion extension; the two are versioned
> and released independently. Full docs:
> [baobaolaodie/dsh-tui-vscode](https://github.com/baobaolaodie/dsh-tui-vscode)
>
> **The selection channel requires an extension that speaks protocol v2**
> (**dsh-tui-vscode >= 0.7.0**); with an older extension the feature stays
> silently disabled and everything else is unaffected.
## Option 1: the dsh-tui-vscode companion extension (recommended)
[`baobaolaodie/dsh-tui-vscode`](https://github.com/baobaolaodie/dsh-tui-vscode)
runs dsh-tui inside a real VS Code integrated terminal (`createTerminal`
plus the CLI running inside it), with no webview and no xterm emulation.
It does not touch the TUI's rendering core — it only **hosts** it and adds
editor integration.
### Extension features
- Editor-title button, activity-bar whale icon, and command-palette entries;
- a `DeepSeek` integrated terminal in a column beside the editor;
- one independent terminal and process per session, with existing sessions
continuing in their own terminals;
- a sidebar session history grouped by project, with refresh and
specific-session resume;
- environment injection for `DSH_TUI_LANG`, `$VISUAL`, `$DSH_HOME`, and a
target session id;
- per-session termination when its terminal closes, or when `Ctrl+C` is
pressed twice inside the TUI.
| Capability | Official Claude Code extension | dsh-tui-vscode |
| --- | --- | --- |
| Entry points | Activity-bar icon + editor-title button + command palette | Same (DeepSeek whale icon) |
| Session position | NEW column beside the active one (`ViewColumn.Beside`) | Same — never takes the current column |
| Terminal tab | `Claude Code` + logo icon | `DeepSeek` + whale icon |
| Session host | Real integrated terminal (default shell — PowerShell on Windows) | Same |
| Multiple sessions | Every click opens a new session terminal | Same; old sessions keep running |
| Sidebar | Sessions list | Session history (grouped by project — stronger) |
| Auto start/stop | Open = start; closing the terminal = end | Same |
| Env injection | — | `DSH_TUI_LANG` / `$VISUAL` / `$DSH_HOME` / session id / `DSH_TUI_IDE_PORT/TOKEN` (selection channel) |
| Editor selection sync | Selection enters context automatically; `⧉ N lines selected` under the prompt | Same (IDE selection channel, below) |
### IDE selection channel
With a dsh-tui build that includes the IDE selection channel, the extension
runs a loopback WebSocket server and writes a lock file (directory 0700,
file 0600).
- Extension-launched sessions connect via injected env vars at startup;
- manually launched sessions discover it by scanning the lock — only windows
whose workspace covers the session directory are ever dialed. With no
match the integration stays silently disabled and a foreign project is
never connected.
Afterwards:
- Selecting code in the editor instantly shows a `⧉ N lines selected` badge
under the TUI prompt (it disappears when the selection clears);
- Submitting a message attaches only the selected lines to the model
context, with a `⧉ Selected N lines from <relative path>` indicator above
the user bubble (resuming after a restart still rebuilds that indicator);
- Selection pushes carry the editor buffer's OWN text — unsaved edits are
attached exactly as you see them on screen; oversized selections are
capped and marked with the same policy as @-mentions;
- Without an IDE or on disconnect everything degrades silently with zero
impact on the rest of the TUI.

**Protocol & versions**:
- After connecting, the TUI sends `ide/hello` (token + protocolVersion);
- the extension answers `ide/hello_ack` (protocolVersion + workspaceFolders)
only when the token validates — the link counts as established only after
a valid v2 ack; a wrong token is silently dropped;
- `selection_changed` then carries absolute 0-based inclusive line numbers
plus the editor buffer's own selection text;
- lock discovery only ever dials windows whose workspace covers the session
directory and stays silently disabled without a match;
- both ends of the protocol must ship at the same version.
### Prerequisites
- VS Code >= 1.90;
- Global `dsh` CLI and `dsh-tui` (**dsh-tui 0.7.0+ recommended**, see
[Getting started](getting-started.en.md)):
```sh
npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
```
- `DEEPSEEK_API_KEY` for running models (in the terminal environment or the
dsh configuration).
### Install
**From the VS Code extension panel (recommended)**: press `Ctrl+Shift+X`,
search for **`dsh-tui`** and install with one click (publisher
`baobaolaodie`), or open the
[Marketplace page](https://marketplace.visualstudio.com/items?itemName=baobaolaodie.dsh-tui-vscode)
directly.
Or build from source:
```sh
git clone https://github.com/baobaolaodie/dsh-tui-vscode.git
cd dsh-tui-vscode
npm install
npm run package && code --install-extension dsh-tui-vscode-<version>.vsix --force
# or: npm run install:local
```
### Quick start
1. Click the **editor-title whale button** (or the command-palette entry
`dsh-tui: Start new session / 启动新会话`) — a **DeepSeek** terminal
opens on the Beside column and runs dsh-tui automatically.
2. The **activity-bar whale icon** opens the sidebar session history; its
welcome view offers start/resume buttons.
3. Click again = **another concurrent session**; older sessions keep
running in their own terminals.
4. **Resume the last session**: `dsh-tui: Resume last session / 恢复上次会话`.
5. **Resume a specific session**: expand a project group in the sidebar
"会话历史" and click the session entry.
6. **Terminate**: close the terminal tab (ends only that session), or
double `Ctrl+C` inside the TUI; the command
`dsh-tui: Terminate session / 终止会话` sends Ctrl+C to the most recent
terminal.
While sessions are running, a **status-bar** item (`dsh-tui`, bottom-left)
appears; clicking it starts a new session (`dsh-tui-vscode.open`).
### Command reference
| Command ID | Title | Action |
| --- | --- | --- |
| `dsh-tui-vscode.open` | Open panel / 打开会话面板 | Start a new session (the editor-title button uses this entry point too) |
| `dsh-tui-vscode.start` | Start new session / 启动新会话 | Start a new session |
| `dsh-tui-vscode.resume` | Resume last session / 恢复上次会话 | Resume via `--resume` |
| `dsh-tui-vscode.focus` | Focus session panel / 聚焦会话面板 | Focus the most recent terminal, else start one |
| `dsh-tui-vscode.kill` | Terminate session / 终止会话 | Send Ctrl+C to the most recent terminal |
| `dsh-tui-vscode.refreshSessions` | Refresh sessions / 刷新会话列表 | Manually refresh the sidebar |
| `dsh-tui-vscode.resumeSession` | Resume session / 恢复会话 | Resume a specific session (sidebar click) |
| `dsh-tui-vscode.insertAtMention` | Insert @-mention / 插入 @文件引用 | With editor focus press `Ctrl+Alt+K` (macOS `Cmd+Alt+K`) or the editor context menu: inserts the current file / selection as `@absolute/path Lstart-end` into the dsh-tui input box (the absolute path is independent of the dsh-tui session cwd; whole file when nothing is selected; falls back to the clipboard with no running session) |
### Architecture
- The extension runs a loopback WebSocket server and writes a lock file
(directory 0700, file 0600).
- Extension-launched sessions connect via injected env vars at startup.
- Manually launched sessions (e.g. tmux / SSH) discover it by scanning the
lock — only windows whose workspace covers the session directory are ever
dialed; with no match it stays silently disabled and a foreign project is
never connected.
- The connection speaks protocol v2: the TUI sends `ide/hello`, the
extension answers `ide/hello_ack`, then `selection_changed` pushes
selections.
- Without an IDE or on disconnect, everything degrades silently with zero
impact on the rest of the TUI.
### Configuration
| Key | Default | Description |
| --- | --- | --- |
| `dsh-tui-vscode.command` | `dsh-tui` | Launch command (resolved to an absolute path against the host PATH) |
| `dsh-tui-vscode.extraArgs` | `[]` | Extra CLI args, e.g. `["--lang","en"]` |
| `dsh-tui-vscode.lang` | `""` | `""`/`zh`/`en`, exported as `DSH_TUI_LANG` |
| `dsh-tui-vscode.injectEditor` | `true` | Export `$VISUAL` when unset |
| `dsh-tui-vscode.editorCommand` | `code -w` | Value exported as `$VISUAL` |
| `dsh-tui-vscode.dshHome` | `""` | `$DSH_HOME` override (empty = inherit) |
### Development and verification
Entry-level commands in the extension repository:
```sh
npm install
npm run typecheck # tsc --noEmit
npm test # compile + node --test (data-layer unit tests)
npm run test:e2e # real extension-host tests (xvfb-run -a on Linux)
npm run package # compile + build the .vsix
```
`npm run install:local` installs locally in one step; the CI job matrix and
commit hooks live in the extension repository's own docs.
### Known limitations
- Session content is terminal content: scrollback is managed by the VS Code
integrated terminal;
- Specific-session resume requires this profile's `cordis.patch.yml`
(dsh-tui 0.7.0+);
- For logs without a `session` header, the project name comes from decoding
the cwd-encoded group dir, which is lossy for hyphenated project names
(e.g. `flow-comet` → `flow\comet`); the real cwd is still available in
the item tooltip.
## Option 2: run directly in the VS Code integrated terminal
When you do not want the extension, run dsh-tui directly in the integrated
terminal. Prerequisites match [Getting started](getting-started.en.md):
global `dsh` CLI and `dsh-tui` (the first run bootstraps the profile; pnpm
is required).
1. Open the VS Code integrated terminal (`` Ctrl+` ``) and run:
```sh
dsh-tui
```
2. Resume the last session:
```sh
dsh-tui --resume
```
> `-c` / `--continue` is equivalent to `--resume`; `dsh-tui --resume <id>`
> (or `--resume=<id>`, since 0.7.0) resumes a specific session.
dsh-TUI has dedicated compatibility paths for xterm.js (VS Code / Cursor /
code-server):
- truecolor;
- OSC 8 links (rendered clickable by VS Code itself);
- OSC 52 clipboard (VS Code prompts for permission on first use);
- synchronized output and smooth draining.
These are handled in `src/ink/` under the `TERM_PROGRAM=vscode` detection
branches. Streaming Markdown, tool cards, scrolling, and double-Esc time
travel behave the same as in a standalone terminal.
### Make `Ctrl+G` edit the current input in VS Code
The TUI's `Ctrl+G` uses `$VISUAL`/`$EDITOR`. To edit in VS Code, export
`code -w` in the terminal environment (`settings.json`, key
`terminal.integrated.env.<platform>`):
```jsonc
{
"terminal.integrated.env.windows": { "VISUAL": "code -w" },
"terminal.integrated.env.linux": { "VISUAL": "code -w" },
"terminal.integrated.env.osx": { "VISUAL": "code -w" }
}
```
(The companion extension exports `code -w` automatically when neither
`$VISUAL` nor `$EDITOR` is set — see Option 1.)
### UI language
`DSH_TUI_LANG` defaults to Chinese; for the English UI, add
`"DSH_TUI_LANG": "en"` to the env block above.
### Known differences (built-in terminal)
| Capability | Behavior in the integrated terminal |
| --- | --- |
| Mouse wheel / drag selection | Handled by the integrated terminal; "copy on release" surfaces as OS-level copy behavior |
| Extended keyboard protocol | modifyOtherKeys / win32-input-mode behavior is decided by xterm.js and may differ from kitty / WezTerm |
| OSC 52 clipboard | First use triggers VS Code's own permission prompt |
| Image protocol | Portraits/images can stay **permanently blank**: dsh-tui prefers the Kitty graphics protocol over Sixel, while VS Code's `@xterm/addon-image` answers the Kitty query with an `OK` that was never verified against an actual draw, so the image is erased and never redrawn. Fix: turn on `terminal.integrated.enableImages` (off by default) in VS Code settings and **reload the window** (the image addon only loads on the WebGL renderer, so it does nothing when `terminal.integrated.gpuAcceleration` is `off` or the legacy `canvas`); if needed, set `DSH_TUI_IMAGE_PROTOCOL=sixel` (needs dsh-tui ≥ 0.10.0) — the companion extension `dsh-tui-vscode` ≥ 0.7.5 injects that variable automatically, so no manual setup is required |
For the full protocol behavior of a standalone terminal (e.g. complex mouse
semantics), use an external terminal window (Windows Terminal / kitty /
WezTerm / iTerm2 / tmux).
## Which option to choose
| Scenario | Choice |
| --- | --- |
| Need multiple sessions, session history, and specific-session resume | Option 1: companion extension |
| Occasional use, no extension wanted | Option 2: built-in terminal |
| Need a standalone terminal's full protocol behavior (complex mouse semantics, etc.) | External terminal window |
## Acceptance baseline
Per [Contributing](contributing.en.md), VS Code is a supported terminal
platform. Any rendering change should be walked through inside the VS Code
integrated terminal in both inline and fullscreen modes at narrow widths —
startup, resize, scroll, input, cancel, and clean exit.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |