English | 简体中文
dsh-tui-pi
A fully-featured pi-style terminal UI for DeepSeek Harness (dsh) — a plugin suite that turns dsh into a pi-like coding-agent experience: /history look-back & fork-at-turn, guided preset switching, live subagent steering, model profiles, 20+ built-in themes (10 light + 10 dark) with user theme directory discovery, and a powerline footer.
Requires dsh >= 0.2.0-rc.2 — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the latest/next dist-tags at runtime). The alpha line is no longer supported. A startup guard logs a one-line warning and exits cleanly when the host is older than the floor (opt out with DSH_TUI_SKIP_HOST_CHECK=1). See ADR 0002 for the now-superseded alpha single-target decision.
https://github.com/user-attachments/assets/67a7c6ca-ff42-4005-b543-437ba61771bb
A live recording of a session (MP4, 1.5× speed) — todos, running subagents, think/tool panels and the powerline footer in action.
✨ Features
Each item links to its own doc under docs/features/ — one line here, the details (and demo videos) there.
- Footer — live session overview — provider/model, context pressure and the session cache-hit rate at a glance, always in view.
- Think & tool panels — reasoning and tool activity stay out of the transcript, so the conversation reads clean.
- Subagents — every running subagent gets a status line; watch its live transcript and decode speed (tok/s), steer it in place.
- Tool approvals — review the operation and allow it once or deny it; no automatic approval.
- Ask User Question — the model can pause and ask you structured questions, answered without leaving the TUI.
- Feishu integration — dsh-tui-pi on the desktop and Feishu/Lark on the phone driving (and answering for) the same dsh session.
- Dynamic context pruning (DCP) — context stays within limits automatically, with zero LLM calls.
- Persistent context — your ground rules ride along on every request, hot-applied with no restart.
- Model profiles & favorites — profile switching lives in dsh-profile-switch now; this suite keeps the TUI read side (session seeding from the pin, live-selection bridge, scope-aware
/agents edits) and the /model favorites that keep the picker small.
- Agent preset switching —
/preset between the agent presets the host's 0.1.7 registry declares (standard, minimal, …); a switch is confirmed and starts a NEW session on the preset (the current one stays resumable); what a preset really gates, and how to migrate a 0.1.5 directory preset (same-id bundle patch).
- Sessions & resume — sessions stay tidy automatically and resume in a few keystrokes;
/session breaks out the session's decode speed and per-model usage; the host's kernel write lease keeps the log single-writer across processes.
- History browser —
/history opens a fixed two-pane look-back over the session: completed turns on the left, the selected turn's replies on the right; copy a prompt back to the editor, or cold-read any stored session without resuming it (read-only).
- Themes — 20 built-in palettes (10 light + 10 dark) plus user theme discovery (
~/.dsh/themes/); hot-switchable, auto follows your terminal.
- Search, selection & images — two searches:
Ctrl+Shift+F searches THIS session's transcript (pi-tui built-in) while /search (or Ctrl+Alt+F) full-text searches EVERY stored session — best-match snippet per hit, Enter opens it (↳ subagent-child hits browse read-only); drag-select copies to the OS clipboard, attachments from web/Feishu render inline, LaTeX replies draw as Unicode math.
- Slash commands —
/model, /resume, /btw, /plugins, /search, … plus everything dsh-native.
- Plugin manager —
/plugins toggles bundles on/off, uninstalls behind a confirm, installs a spec (npm name / git URL / path / tarball) after an inspect preview; every change reports applied / takes effect at the next start / failed inline.
- Settings browser & UI languages —
/settings edits everything in place (alphabetical categories, per-provider model lists, a Subagent group); /language switches the UI language from any surface.
- Startup plugin tree — every profile plugin with its installed npm version, printed at launch.
Install and launch
npm i -g @aiwayds/dsh-tui-pi
dsh-tui-pi # or the short form: dst
The global install sets the machine up by itself, printing one progress line per step: it installs the @deepseek-ai/dsh host when missing (via npm, resolved as the newest of the latest/next dist-tags — the latest tag alone lags the rc line; if npm itself is not on PATH, it prints what to install and stops), installs pnpm, and creates the tui profile with this plugin and its bundled companions. Host compatibility window: 0.2.1-rc.2 through 0.2.1-rc.4 — an rc.2 host is kept as-is (the subagent companion degrades gracefully there); an older one is upgraded automatically. Whatever the install cannot finish (e.g. an offline machine) completes automatically on the first launch. After a later npm i -g upgrade of this package, the profile's mounted copy is moved to the new version on the next launch — a profile that is newer than the global install (dev-upgraded ahead) is left untouched.
The manual steps do exactly what the onboarding runs, if you prefer them:
npm i -g @deepseek-ai/dsh
npm i -g pnpm
dsh plugin --profile tui add @aiwayds/dsh-tui-pi
dsh --profile tui # launch
Never add @deepseek-ai/* packages to a profile by hand — the host provides them, and their npm latest tag is a 0.0.1 stub (a bare-name pnpm add @deepseek-ai/dsh-llm lands that stub next to the plugin and shadows the host's copy; the symptom is the loader's does not provide an export named … and the plugin not activating). The dsh-tui-pi launcher checks for exactly this before every boot and, when it finds a shadowing copy, stops with both paths, both versions and the removal commands instead of booting into the broken state.
Legacy session_projcache records (written before dsh 0.1.2-alpha.4) are migrated automatically at profile load — idempotent, with per-file backups, never blocking startup; the dsh-tui-pi launcher runs the same preflight.
Everything that used to need manual patching — the canvas background, the @deepseek-ai module closure, the compaction backend — now happens automatically. For a normal install, upgrading the global package upgrades the profile on the next launch (see above). dev-upgrade remains for dev machines that install the profile from a checked-out repo:
node scripts/dev-upgrade.mjs # latest
node scripts/dev-upgrade.mjs 1.0.5 --dry-run # preview the plan first
Uninstall
dsh plugin --profile <name> remove @aiwayds/dsh-tui-pi
The dsh-tui-pi bin shim is global and can stay; if you installed the package globally and want it gone too: npm -g rm @aiwayds/dsh-tui-pi.
The host cleans up the profile automatically: the dsh.profile.bundles entry is spliced and the whole patch layer goes away with the package — the stock session-projection-cache row re-enables, and the projcache wrapper, the tool-ask-user insert and its disable row all vanish.
User data stays on disk on purpose (deleting it is destructive; a reinstall reuses all of it): ~/.dsh/APPEND_SYSTEM.md, tui-command-usage.json, model-profiles.json, keybindings.json, ~/.dsh/agents/ + ~/.dsh/skills/, workspace .dsh-profile pins, the dsh-tui entry config in the profile patch (a pre-0.1.7 settings.yaml section lands there as settings.yaml.imported), and the session projection cache (incl. .bak-preflight-* migration backups). While the plugin runs, the retention janitor (default maxCount: 300 / maxAgeDays: 90) deletes old session logs — uninstalling stops that, but already-deleted logs are gone. scripts/install-font.mjs mutates OS font/terminal state and has a documented backup; uninstall doesn't touch it.
Companion plugins
Default dependencies — the nine plugins below ship with this package (installed into the profile's node_modules); activation still follows the profile's bundles list — list each one there to activate it.
Recommended install — @aiwayds/dsh-topics-memory, OKF topic memory for dsh (zero-LLM hot-path injection + a local git-tracked bundle; formerly dsh-llmwiki-memory):
dsh plugin --profile tui add @aiwayds/dsh-topics-memory
Optional — @aiwayds/dsh-feishu — drives the same dsh session from Feishu/Lark on your phone (demo).
Keyboard shortcuts
| Key | Action |
|---|
Enter | Send the prompt |
Esc | Double-press to stop everything — the first press arms, the second opens a confirmation dialog naming what is running (main turn + subagent count); Enter there stops the main turn AND every running subagent, Esc keeps everything running. A popup open closes it instead. Works while only background subagents run. |
Ctrl+C | Mid-task: first press stops (same everything-stop, no dialog), second quits; idle: clears editor / quits. Held-key auto-repeat never quits. |
Ctrl+D | Quit (only when the editor is empty) |
Ctrl+L | Open the model/think picker |
Ctrl+G | Open the subagent picker (viewer Enter opens steer, x ×2 stops that subagent while it runs / closes when settled) |
Ctrl+O | Pending-message queue (s steer now · d remove) |
Ctrl+Shift+F | Transcript search (pi-tui built-in): Enter/Ctrl+G next match, Shift+Enter/Ctrl+Shift+G previous, Esc close |
Ctrl+Alt+F | Cross-session full-text search — same as /search: Enter opens the hit (resume; ↳ child rows open a read-only browse), n loads more, q starts a new query, Esc close. /search works everywhere; the chord arrives as the legacy ESC+Ctrl+F encoding on most terminals |
↑ / ↓ | Browse submitted-message history |
Remap any app key through ~/.dsh/keybindings.json (a partial JSON map, live-applied) or interactively with /hotkeys.
Configuration
Everything lives in the plugin's dsh-tui entry config inside your profile's cordis.patch.yml (dsh 0.1.7 projects every volatile field of a plugin's declared Config schema into the settings surface) — but you rarely touch the file: /settings browses and edits it in place (searchable categories — Agent Presets / General / Models / Plugins / TUI — with live values, per-field descriptions, and an add-provider flow under Models). Language, theme, panel height, footer hints and icon set hot-apply on change; the rest reads at the next launch.
Most knobs have sensible defaults and need no configuration. The few you might actually set:
- id: dsh-tui # the plugin's entry row in the profile patch
config:
language: zh-CN # UI language — or just /language (asks on any surface; bundled: en, zh-CN, ja, ko)
theme: auto # auto / light / dark / any registered theme name — or /theme
maxAgents: 4 # subagent concurrency, 0 = unlimited (also tunable in /agents → l)
/agents → l also mirrors the OFFICIAL dsh-subagent caps (maxActiveSubagents, default 8; maxDepth, default 1) as read-only rows — those belong to the subagent plugin entry and are edited in /settings, while the panel's own rows (maxAgents / maxRounds / maxRoundsGrace / the two fences) stay hot-editable here.
Upgrading from dsh 0.1.5? Your old ~/.dsh/settings.yaml dsh-tui: section is imported into the profile automatically on the first 0.1.7 boot (the original file is kept next to it as settings.yaml.imported).
Adding a UI language is one JSON file in ~/.dsh/locales/ — a same-id file merges per key over the bundled one, a new id registers (details: Settings browser & UI languages). The session-store janitors (retention / resume) and ask-user timeouts (askUser) live in the same entry config with documented defaults.
The plugin ships a bundled skill (dsh-tui-pi-config): ask the agent to "configure the TUI" and it collects your choices interactively and writes the section for you. The full key table and the DSH_TUI_* env var list live in skills/dsh-tui-pi-config/SKILL.md.
Development
pnpm check # tsc --noEmit
pnpm build # emit lib/
pnpm test # unit tests, node --test against lib/ (pretest builds — the current baseline lives in AGENTS.md)
pi-tui runs pristine from npm — no patches, no fork. See AGENTS.md for the iron rules and quality gates.
Documentation
- docs/features/ — one doc per feature, with demo videos.
- ARCHITECTURE.md — full design: process model, layers, data flow.
- CHANGELOG.md — release history.
- AGENTS.md — working conventions and quality gates for contributors.
- docs/ — design notes (steer/follow-up flow, showcase drafts, …).
Compatibility note
Resuming, under a dsh 0.1.6 host, a session saved under dsh 0.1.5-rc.2 whose subagent completion notices carried reasoning content fails to serialize the first model request (upstream B-21 — host-side data issue, not a plugin defect). If /resume fails this way, start a new session instead.
Credits
The Ask User Question interaction is inspired by juicesharp/rpiv-ask-user-question (adapted to this TUI's docked-panel and dsh userQuestions provider architecture; all code here is original).
