dsh-TUI

An interactive terminal UI plugin for DeepSeek Harness. It ships a pixel-whale header, live work status, streaming thinking, double-Esc time rewind, a context progress bar, and a TPS gauge. It mounts as a pure plugin, with no core changes. Install to enable; uninstall leaves no patches behind.

Highlights

• Pixel whale pet — three startup intros, click to wake; freezes after the first task.
• Terminal-native UI — streaming Markdown, tool cards, / and @ completion, #L12-14 ranges, history search, zh/en UI.
• Images — Kitty/Sixel thumbnails, centered preview with zoom and pan, paste-time fitting, text fallback.
• Mermaid diagrams — mermaid fences drawn as Unicode diagrams.
• LaTeX math — $…$ and $$…$$ formulas rendered as Unicode, fractions and limits stacked in display blocks.
• Timeline rail — every turn clickable; timeline / scrollbar / hidden gutter.
• Live state — activity animation, context bar, TPS, cache hit rate, effort, tokens, Git and session metadata.
• One session manager — /resume /home /agentview /bg ⌸.
• Session workflow — /new /compact /export /btw, model hot-switch, fork, rewind, vim, fullscreen draft editor.
• IDE selection channel — a VS Code selection lands in the prompt.
• DSH integrations — presets, skills, MCP, goals, todos, subagents, questionnaires.
• Extensions — browser interaction, computer use and more.
• Built for long sessions — event-driven projection, virtualization, bounded caches.

Keys and commands: Interaction and commands. Everything else: documentation index.

Preview

Featured & Listed

Featured by the DeepSeek Harness official WeChat account, listed in the dshfind plugin directory, and ranked #7 on GitHub Trending daily (TypeScript).

Quick Start

Prerequisites: Node.js and deepseek-harness, with DEEPSEEK_API_KEY configured.

The primary compatibility target is DSH 0.1.7-rc.2. This adapter supports its Shell API, V4 session messages, declarative presets, and profile-backed settings; older supported hosts retain their compatibility paths. See configuration.

On DSH 0.1.7, /settings uses the TUI's actual Loader entry ID, including custom IDs. It requires matching profile dependencies with @deepseek-ai/schemastery 3.18.3 or newer; an incompatible schema stops TUI startup with repair guidance instead of showing an uneditable settings page. Older hosts keep their legacy settings scope.

# Install the CLI and this plugin globally (ships the dsh-tui command)
npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui

# Start (first run auto-initializes the profile; needs pnpm)
dsh-tui
# Both `dsh-tui` and the short `dst` alias start the same TUI.
dst

Manual alternative: dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui. The repo's sh install.sh runs that step and checks the required commands. Afterwards dsh-tui and dsh --profile dsh-tui are equivalent.

New-user note: pnpm ≥11 blocks dependencies with install scripts by default and reports ERR_PNPM_IGNORED_BUILDS. Updates skip foreign-platform @img/sharp-* native packages, saving about 200MB of downloads. /update and dsh-tui update write both settings automatically. No manual step needed. Details: Getting started.

After startup the TUI checks for newer versions in the background. It never blocks the first frame. Type /update for a one-shot upgrade. It restarts automatically and resumes the current session. See Getting started for the profile lifecycle, source builds, and troubleshooting, including migration from the former dsh-cc-tui package.

CLI

Other arguments go to dsh --profile dsh-tui. Safe mode: Getting started.

Importing conversations from other agents (dsh-tui migrate)

Bring Claude Code, Codex, OMP, zcode, or Grok Build conversation histories into the DSH session store, then browse and resume them by their original working directory via /resume:

dsh-tui migrate                # list importable counts per agent (writes nothing)
dsh-tui migrate claude-code    # import every Claude Code conversation (likewise codex / omp / zcode / grok-build)
dsh-tui migrate codex --dry-run  # preview what would land, write nothing

• Read-only source: migration only reads the foreign agent's local store; artifacts are written through the official JsonlSessionPersistence backend, so imported sessions are first-class (openable, continuable).

• Idempotent: one deterministic UUID per source conversation — re-importing skips what is already present instead of stacking duplicates.

• Structure preserved: user/assistant messages and reasoning traces are rebuilt turn by turn; tool traffic is not migrated (source formats cannot replay it faithfully — the contract is "re-read the conversation", not "resume the task"). In-TUI: /migrate (optionally /migrate <agent> [--dry-run]) runs the same import in a child process and reports through the notification flow. CLI alternative: dsh-tui migrate ... from any shell runs the same import. Full guide: Session migration.

• More agents (pi, opencode, …) extend the adapter registry as adapters land; grok-build reads GROK_HOME when set.

VS Code: use the integrated terminal or the dsh-tui-vscode extension. See VS Code guide. Herdr: run dsh-tui in a Herdr pane; idle / working / blocked are reported through its local integration API.

Keybindings & Mouse

Enter send · Tab complete · Ctrl+Enter interrupt and send · Alt+Up recall the last message · Esc dismiss, double-Esc rewinds · Ctrl+O details · Ctrl+R history · Ctrl+V paste · Ctrl+Shift+E fullscreen draft editor · ? shortcuts · ← background the session.

While the model is working: Enter steers, Tab queues a follow-up, Ctrl+Enter interrupts and sends.

Mouse (fullscreen): drag to select and copy, double/triple click to select a word or line, click tool cards, timeline ticks and [Image #N] previews.

Full reference: Interaction and commands.

Built-in Commands

/resume · /home · /agentview · /bg · ⌸ open the same session manager: workspace rail, live state, filter, ★ pins. Also /model /new /compact /export /btw /tree /fork /rewind /settings /status /cost /jobs /skills /mcp /login /update.

The session manager paints the last successful list immediately while it checks the persistence store for change