ccch1mneyyy/dsh-TUI

English | 简体中文

dsh-TUI

An interactive terminal UI 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. Zero core changes: it consumes only

DSH's public exports, and is moving from a mounted plugin to an app with its

own entry and composition root, where DSH loads in process as the first-party

backend. Install to enable; uninstall leaves no patches behind.

The prompt footer hides completed goals once the turn is idle; the Todo side panel retains their history. Ctrl+Q folds todos while working and hides/restores the idle goal/todo footer. Clicking its todo header also hides it while idle. Hiding changes only this display: a new goal/todo snapshot or session reveals it again, and /goal clear does not clear todos.

Split diff cards give one-sided additions and deletions the full body width, without an empty opposite pane. Ordinary edits remain side by side, and mixed files choose their layout separately before folding or streaming reveal.

Compaction status stays on one line in narrow panes: phase and cancellation hints yield first, then the label is shortened; elapsed time is shown only as a complete field.

Image files referenced with @path use the same admission and resize/conversion policy as pasted images. Adjustment notices report the stored dimensions and format; required animation conversion is refused instead of dropping frames. Mention images and staged images still share count and stored-byte limits in source order.

Highlights

Panels without a verified Component identity are temporary: settings show their title and a distinct number for this run. Their toggles take effect immediately without being saved, and unrelated settings changes preserve that choice. Old actN:panel entries cannot be mapped safely: remove the placeholder and select the current panel again. Verified Components named actN keep their public runtime address; an explicit selection uses component:actN:panel in saved preferences to avoid claiming an old anonymous entry.

The default reasoning-effort setting offers the current backend/model’s declared tiers, including custom IDs. Saved values absent from that catalog stay visible and stored; while loading or unavailable, only Auto is selectable. On DSH, Auto follows the saved /effort choice, then the configured effort, then the model default. Claude/Codex retain backend preferences for Auto at startup and for resumed sessions; explicitly choosing Auto resets the model default. Explicit settings changes affect the next request; unsupported preferences fall back with a notice and are never forced onto a route.

Resuming a DSH session preserves its recorded reasoning effort (or its live selection when reattaching). The saved default seeds new sessions; explicit /effort and effort-default settings changes still apply to the current session’s next request.

• Pixel whale pet — three startup intros, click to wake; freezes after the first task.
• Launchpad and first-run guide — every ordinary launch lands on a landing page with a real input box (big text + whale + quick actions, dropping whole blocks on short/narrow terminals; whale-girl images use a compact native-canvas footprint instead of leaving a large gap before the title; on by default — /settings launchpad off boots straight into chat); command completion matches chat: Tab fills the input, Enter runs the command and clears it. The first run walks a four-step wizard (API key / language+theme / model+workspace / shortcuts), re-runnable with /setup.
• Terminal-native UI — streaming Markdown, tool cards, / and @ completion, #L12-14 ranges, history search, zh/en UI.
• Task completion notifications — DSH, Claude and Codex notify after successful live work settles, with no queued follow-up or active goal. The title is “dsh-TUI · Task complete”; the body shows the latest settled reply as a single-line plain-text preview (Markdown formatting removed, up to 200 characters). OSC 777/9 apply an additional 2048-byte sequence budget, including title and protocol bytes, preserving whole graphemes. No reply shows only the title; BEL only rings. /settings → Conversation: taskNotifications = unfocused (default), always, or off; notificationMethod = auto (default), osc9, bel, or windows. Auto uses separate title/body fields on Ghostty/WezTerm (OSC 777) and Kitty (OSC 99); iTerm2/Warp and explicit osc9 use a title prefix; other terminals ring the bell; delivery follows your terminal's notification/bell settings. On local Windows, auto resolves to windows, the system's native notifications: a task-completion toast. The first toast registers that user's AppUserModelID under HKCU, the toast appears about 3 seconds after the task ends (the PowerShell cold start that buys the no-extra-install route), and for DSH sessions an enabled, active external DSH notification plugin in the running profile makes dsh-TUI yield to it (no toast, no bell); an installed but disabled plugin does not suppress notifications; if that AppUserModelID cannot be written, the notification falls back to the bell instead of going silent. SSH sessions keep the attached terminal's notification protocol in auto mode; explicit windows still selects the host's native transport. tmux requires set -g allow-passthrough on for OSC notifications and set -g focus-events on for focus reporting. Terminals without focus reporting need always. Replay, cancellation and failures do not notify. Works in inline and fullscreen modes.
• Native cursor — focused text inputs inherit your terminal's cursor shape, color, blinking, and enabled animation or trail effects in both inline and fullscreen modes. The /model picker shows the same cursor during movement between provider tabs, model rows, and effort levels, then hides it after 0.5 seconds at rest; clipped regions fall back to the model row. The session manager also moves this cursor between the workspace rail, session rows, and search box; typing claims the search caret, and navigation returns it to the focused row. Configure animation and trail effects in your terminal.
• Images — Kitty/Sixel thumbnails, centered preview with zoom and pan, paste-time fitting, text fallback. Kitty images scale to the reserved cells' physical pixels, including on HiDPI terminals.
• 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.
• Side panel — Ctrl+B splits the chat with a panel column once the terminal is wide enough; drag the divider to resize it. All eight built-in panels are enabled by default, and so are plugin panels registered later (sidePanel.panels: '*'; untick a row in /settings to switch to an explicit list). The header shows each inactive panel's symbol; hover to see its name. Narrow terminals and inline mode keep full-screen panels.
• Live state — activity animation, context bar, TPS, cache hit rate, effort, tokens, session cost estimate (main + subagents), Git and session metadata. Title, trajectory-strip and session-state animations update independently of the transcript and pause when idle or unfocused.

Context-bar fill follows backend occupancy; colors estimate content composition. Compaction clears obsolete estimates, and missing composition displays a single used block with a measured used count in both hover details.

• One session manager — /resume /home /agentview /bg ⌸.
• Session workflow — /new /compact /export /btw, model hot-switch, fork, rewind, vim, fullscreen draft editor.

/btw uses an overlay when its sidebar cannot render. Main-task questionnaires and the fullscreen draft editor take priority while preserving the side question and draft.

• 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.

Plugin side panels stay enabled when unrelated settings change. Editing the enabled panel list still applies your explicit selection.

Workspace side-panel counts match the session manager: the current conversation counts; empty logs, subagents, fork ancestors and archived sessions do not. Registered workspaces with no visible conversations remain at zero. Loading and read errors are shown separately; press r to refresh.

Fullscreen mouse selection stays in the pane where the gesture starts, including chat, sidebar and either diff column. Diagonal, word and line selection copy that pane’s text; soft wraps join independently, source newlines remain, and divider drags only resize.

Preview

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).

Featured by the official WeChat account Listed in the dshfind directory GitHub Trending Daily #7

Quick Start

Windows one-click installer (x64)

Download dsh-tui-setup-win-x64.exe from Releases and run it. Per-user, no administrator, fully offline, and no preinstalled Node or DSH.

Command-line installation

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.1-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 rc.2, /settings also selects DeepSeek Search / Fetch APIs and edits their endpoint and result limits, supporting custom Loader entry IDs and a masked API key input saved through DSH's credential store. Official Flash model labels show the 1017 release marker while retaining the deepseek-flash model ID.

/settings groups its sections into pages: the TUI's own settings sit under General, and plugins that declare a page get their own tab (Tab / Shift+Tab, or a click on the strip in fullscreen, switches pages; the strip is hidden when only one page exists).

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.

The dsh-tui section of /settings is saved in ~/.dsh-tui/settings.json, shared by every kernel; the first launch imports it once from the profile's cordis.patch.yml (and an older host's ~/.dsh/settings.yaml) (see configuration).

# 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

natives — the @img/sharp-* packages and the Claude SDK's per-platform

bundles — so only this machine's binaries are fetched. /update and

dsh-tui update write both settings automatically. An update never installs

the Claude SDK on its own: it enters a profile only when you pick that

backend in the kernel picker, which then installs the pinned SDK for the

running platform. 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

Automation: dst -p "task", dst run --json, dst session list --json. The independent engine does not load the TUI or inherit its profile/preferences; it uses official DSH headless/services (validated on 0.2.0-rc.2 and 0.2.1-rc.2). dst cli --help lists its commands; dst dsh forwards native DSH. See Automation CLI for protocol, limits, resume restrictions, and Node/Python/PowerShell integration examples.

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 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 [--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. Any terminal: dsh-tui reports idle / working / blocked / done / error over the pty with OSC 7501 (Program Status Protocol), so terminals and agentic inboxes that implement it can show what the session is doing; terminals that do not implement it ignore the sequence. Set DSH_TUI_PROGRAM_STATUS=0 to turn it off.

Bare --resume (-c, --continue) reopens the last session of the backend this launch selected. Startup recovery only ever targets that backend: a backend with no last session, or a derived target that belongs to a different backend than the one that actually booted (an unknown backend id falling back to DSH, --backend naming a backend that is not installed, a remembered kernel that is not the marker's source), refuses with a clear error and exit code 1 — never a silent cold start, never another backend's session, never a new session. An explicit --resume passes that id to the selected backend as-is. The one exception is safe mode's "retry normal startup": it retries the kernel and session recorded in last-run.json, so a record whose backend is gone degrades to a warning plus a cold start — that retry is the last way back.

Experimental: Claude backend

dsh-TUI can also run its session on Claude: the same interface, driving the Claude Code CLI through the Claude Agent SDK. Your project's CLAUDE.md, settings, hooks, MCP servers and plugins load as the CLI loads them.

# once, in the dsh-tui profile directory (the SDK is an optional dependency)
cd ~/.dsh/profiles/dsh-tui && pnpm add @anthropic-ai/claude-agent-sdk@0.3.287
dsh-tui --backend claude     # or pick Claude in /kernel; that choice is remembered

The easiest install: open the kernel picker (the launchpad "Kernel" entry or /kernel) and press Enter on the dim Claude row — the wizard locates the profile directory and installs the pinned SDK for you; the command above is its manual equivalent. The confirmation shows the exact package and version. Closing the wizard, including clicking outside it on the launchpad, cancels a pending installation.

• Sign-in: a /channel relay profile, your dsh-auth anthropic sign-in

(/login), ANTHROPIC_API_KEY or cloud-provider variables, or an existing claude login, in that order. A claude on PATH is used when present, then one in the native install directory under your home (~/.local/bin, or %USERPROFILE%.local\bin on Windows); every candidate has to launch and report a version, and the SDK's bundled binary is used only when none does.

• Works: streaming, tool cards, approvals and questions, /model,

/effort, Claude's permission modes (/permission, Shift+Tab), /compact, /context, /mcp, /resume, /fork, double-Esc rewind, subagents, background jobs, images, /btw, and the USD cost Claude reports.

• Not available: DSH-only commands such as /tree, /preset,

/provider, /workspace, /agentview and /bg. One process runs one backend; /kernel switches by restarting into a new session.

• Startup: the screen appears before the session opens, with only a light

profile composed (this package plus the profile's third-party plugins); see Claude backend. The DSH kernel starts from the same entry and loads DSH in the same process behind its first screen; DSH_TUI_HOST_ENTRY=0 restores the old launch path for every kernel.

Details and known limitations: Claude backend.

Experimental: native Codex backend