<p align="center"> <img src="docs/assets/readme/logo-en.svg" alt="dsh-TUI animated whale logo" width="560"> </p> <p align="center"> <strong>English</strong> | <a href="README_ZH.md">简体中文</a> </p> <p align="center"> <a href="https://www.npmjs.com/package/@deepseek-harness-tui/dsh-tui"><img alt="npm" src="https://img.shields.io/npm/v/@deepseek-harness-tui/dsh-tui?style=flat-square&color=4b6fff"></a> <a href="https://github.com/ccch1mneyyy/dsh-TUI/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ccch1mneyyy/dsh-TUI/actions/workflows/ci.yml/badge.svg"></a> <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a> <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square"> <a href="https://github.com/ccch1mneyyy/dsh-TUI/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ccch1mneyyy/dsh-TUI?style=flat-square&color=4b6fff"></a> <a href="https://www.npmjs.com/package/@deepseek-harness-tui/dsh-tui"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@deepseek-harness-tui/dsh-tui?style=flat-square&color=4b6fff"></a> </p>

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 as Unicode text, fractions and limits stacked in display blocks; mathRendering: image typesets block and one-row inline formulas as terminal images on graphics terminals.
• Timeline rail — every turn clickable; timeline / scrollbar / hidden gutter.
• Live state — activity animation, context bar, TPS, cache hit rate, effort, tokens, session cost estimate (main + subagents), 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.
• Account sign-in — the standard profile offers pi-ai OAuth for ChatGPT/Codex, Claude, and Grok (plus OpenAI direct and Meta Muse when available), and Host-owned DeepSeek browser sign-in as deepseek-account on DSH 0.2.0-rc.1+. Use /provider or /auth without another plugin. A profile-only update from a global TUI patch that already mounts dsh-tui-auth can still start the official loopback callback listener on demand; fixed-port SSH forwarding still requires the global package to be aligned.
• 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

<div align="center"> <picture> <source media="(max-width: 640px)" srcset="docs/assets/readme/preview-en-mobile.svg"> <img src="docs/assets/readme/preview-en.svg" alt="Recorded dsh-TUI session: welcome, completion, help and typing, with animated pixel whale." width="78%"> </picture> </div>

Featured & Listed

Among the community plugins recommended by the official lead of DeepSeek Harness, dsh-TUI is the first.

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

<div align="center"> <table> <tr> <td align="center" valign="middle" width="50%"> <img src="screenshots/wechat-official.png" alt="dsh-TUI featured by the DeepSeek Harness official WeChat account" width="480"> <br> <strong>Featured by the official WeChat account</strong> </td> <td align="center" valign="middle" width="50%"> <a href="https://dshfind.com/en/plugins/ccch1mneyyy/dsh-TUI"><img src="https://dshfind.com/api/card/ccch1mneyyy/dsh-TUI?lang=en" alt="dsh-TUI on dshfind" width="420"></a> <br> <strong>Listed in the dshfind directory</strong> <br><br> <a href="https://trendshift.io/repositories/146168" title="GitHub Trending Daily #7 · TypeScript"><img alt="Trendshift" src="https://trendshift.io/api/badge/trendshift/repositories/146168/daily?language=TypeScript"></a> <br> <strong>GitHub Trending Daily #7</strong> </td> </tr> </table> </div>

Quick Start

Prerequisites: Node.js and deepseek-harness. The deepseek-official API-key route needs DEEPSEEK_API_KEY. On DSH 0.2.0-rc.1+, the standard profile can instead use /auth login deepseek-account and select the separate account route through /model. Other supported accounts can sign in through /provider or /auth after startup.

The primary compatibility target is DSH 0.2.0-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

| Command | Purpose | | --- | --- | | dsh-tui / dst | Start the TUI; dst is a short alias for the same program | | dsh-tui --resume [id] · dsh-tui update · dsh-tui doctor | Resume a session · update the profile and align the launcher · pre-flight environment checks | | dsh-tui safe | Read-only diagnostics, plugin inventory and repair guidance; safe --rescue builds a clean rescue profile | | dsh-tui version · dsh-tui help | Launcher and profile versions and usage; both work even without a dsh install |

Leading DSH options such as --dump-config and --patch <path> are forwarded unchanged; other arguments go to the app in dsh --profile dsh-tui. Use dsh-tui -- --resume=sid-1 ./notes to send --resume=sid-1 ./notes as literal prompt text, without selecting a session or workspace. When invoking DSH directly, use dsh --profile dsh-tui -- -- --resume=sid-1 ./notes: the first -- belongs to DSH, the second to the app. Host options can precede a literal prompt: dsh-tui --patch ./overlay.yml -- --resume=sid-1 applies the overlay and sends --resume=sid-1 as prompt text without resuming that session. 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, reasoning traces, tool calls with their results, and the source's context compactions (as native compaction checkpoints) are rebuilt turn by turn; harness-injected machine text opens no turn. An imported session can pick the work straight up. In-TUI browsing: the session screen (/resume) shows a tab per agent that has conversations; picking one imports just that conversation and opens it. 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 (↑/↓ and Ctrl+R are scoped to the current project) · Ctrl+V paste · Ctrl+Z undo draft · 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.

On native Windows, fragmented Win32 input records are reassembled across short input delays instead of appearing as numeric protocol text. The platform check only reports that this machine might run the private mode (win32-input-mode); a bare ESC[ fragment is held only after one record has actually been decoded, while a fragment whose own shape is already record-specific holds on its own (which is how even the first record can survive a split). Windows terminals that never enter the mode (mintty, GitBash) therefore keep the classic VT path: a lone Esc keeps its normal response time, and a letter typed after a timed-out ESC[ is not swallowed.

Incomplete records are held for a bounded recovery window (1 second from first capture, never extended b