Skip to content
Back to search

dsh-TUI

DSH's officially top-recommended TUI plugin — high performance, low overhead, cute pixel whale, smooth mouse interaction. One-command install via npm. / DSH 官方首推的 TUI 插件,高性能低占用,可爱像素鲸鱼,流畅鼠标交互,npm 一键安装

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ccch1mneyyy/dsh-TUI with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ccch1mneyyy/dsh-TUI'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ccch1mneyyy--dsh-tui/badge.svg)](/listings/ccch1mneyyy--dsh-tui)

HTML

<a href="/listings/ccch1mneyyy--dsh-tui"><img src="/api/listings/ccch1mneyyy--dsh-tui/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites: [Node.js](https://nodejs.org/en) and [deepseek-harness](https://github.com/deepseek-ai/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](docs/configuration.en.md).

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](docs/getting-started.en.md#pnpm-install-script-blocks-and-foreign-platform-natives).

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](docs/getting-started.en.md) 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](docs/getting-started.en.md).

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)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 805 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/assets/readme/logo-en.svg" alt="dsh-TUI animated whale logo" width="560">
  3. </p>
  4. <p align="center">
  5. <strong>English</strong> | <a href="README_ZH.md">简体中文</a>
  6. </p>
  7. <p align="center">
  8. <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>
  9. <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>
  10. <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
  11. <img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-7da1de?style=flat-square">
  12. <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>
  13. <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>
  14. </p>
  15. # dsh-TUI
  16. > An interactive terminal UI for DeepSeek Harness. It ships a pixel-whale
  17. > header, live work status, streaming thinking, double-Esc time rewind, a
  18. > context progress bar, and a TPS gauge. Zero core changes: it consumes only
  19. > DSH's public exports, and is moving from a mounted plugin to an app with its
  20. > own entry and composition root, where DSH loads in process as the first-party
  21. > backend. Install to enable; uninstall leaves no patches behind.
  22. 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.
  23. 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.
  24. 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.
  25. 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.
  26. ## Highlights
  27. 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.
  28. 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.
  29. 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.
  30. - **Pixel whale pet** — three startup intros, click to wake; freezes after the first task.
  31. - **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 (accounts & models / language+theme / model+workspace / shortcuts), re-runnable with `/setup`; its first step signs in to a subscription and catches the models it brings in (none → no question, one → that one, several → you choose), or adds an API key through the `/provider` wizard, which asks which of the enabled models to switch to or keeps the current one.
  32. - **Terminal-native UI** — streaming Markdown, tool cards, `/` and `@` completion, `#L12-14` ranges, history search, zh/en UI.
  33. - **Notifications** — one switch covers four system notifications: task completion, a tool approval waiting for your decision, a question waiting for your answer, and a plan review waiting for your decision. Completion on DSH, Claude and Codex fires once live work settles, with no queued follow-up or active goal; its title is “dsh-TUI · Task complete” and the body previews the latest reply as one plain-text line (up to 200 characters). Approvals are titled “dsh-TUI · Approval needed” (session name, tool name, reason — never the command); questions “dsh-TUI · Waiting for your answer” (the first question's header and question); plan reviews “dsh-TUI · Plan review” (the question header and question, never the plan). `/settings` → Conversation: `taskNotifications` = `unfocused` (default), `always` or `off`; `notificationMethod` = `auto` (default), `osc9`, `bel` or `windows`. `auto` follows your terminal — OSC 777 on Ghostty/WezTerm, OSC 99 on Kitty, a title prefix on iTerm2/Warp, a bell elsewhere — and resolves to the native system toast on local Windows. On local Windows, an enabled, active external DSH notification plugin makes dsh-TUI yield completions, approvals and questions; a plan review is always sent by dsh-TUI itself. `off` silences all four; only the current session's approvals notify (background sessions and subagents stay quiet); replay, cancellation and failures do not notify. Delivery details, terminal requirements (tmux and the like) and jump-back (`jumpBack`): see the [User guide](docs/user-guide.en.md#53-the-settings-editor) and [terminal requirements](docs/user-guide.en.md#54-terminal-requirements).
  34. - **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.
  35. - **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.
  36. - **Mermaid diagrams** — ````mermaid ```` fences drawn as Unicode diagrams.
  37. - **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.
  38. - **Timeline rail** — every turn clickable; timeline / scrollbar / hidden gutter.
  39. - **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. In the `todo` panel a long goal wraps to the panel width with its phase on a separate row; when the content exceeds the viewport, focus the panel and scroll with `↑`/`↓` or the wheel (every todo is reachable too) (the compact goal row above the chat input stays a single truncated line with a hover tooltip).
  40. - **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.
  41. 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.
  42. - **One session manager** — `/resume` `/home` `/agentview` `/bg` `⌸`.
  43. - Live Compact partial checkpoints appear as folded summaries in chat and summary entries in `/tree`; they do not reset the whole context composition. Occupancy follows the host token meter. Folded previews use the durable summary with the same compactionId; expansion retains the complete text, which is also the fallback when the summary event is missing.
  44. - **Session workflow** — `/new` `/compact` `/export` `/btw`, model hot-switch, fork, rewind, vim, fullscreen draft editor.
  45. `/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.
  46. - **IDE selection channel** — a VS Code selection lands in the prompt.
  47. - **DSH integrations** — presets, skills, MCP, goals, todos, subagents, questionnaires.
  48. - **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.
  49. 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.
  50. - **Extensions** — browser interaction, computer use and more.
  51. - **Built for long sessions** — event-driven projection, virtualization, bounded caches.
  52. Keys and commands: [Interaction and commands](docs/interaction.en.md). Everything else: [documentation index](docs/README.md).
  53. Plugin side panels stay enabled when unrelated settings change. Editing the enabled panel list still applies your explicit selection.
  54. 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.
  55. When a DSH 0.2.1+ Agent moves its session to another directory (the `working_directory` tool or a Git worktree), the status line, Git branch, `@` completion, `!` commands, clicked paths, skill commands and loaded context follow it, including after `/resume`. The session stays registered under the project it started in. Relative paths in cards rendered before a move resolve against the session's current directory when clicked; absolute paths keep their target.
  56. 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.
  57. ## Preview
  58. <div align="center">
  59. <picture>
  60. <source media="(max-width: 640px)" srcset="docs/assets/readme/preview-en-mobile.svg">
  61. <img src="docs/assets/readme/preview-en.svg" alt="Recorded dsh-TUI session: welcome, completion, help and typing, with animated pixel whale." width="78%">
  62. </picture>
  63. </div>
  64. ## Featured & Listed
  65. Among the community plugins recommended by the **official lead of DeepSeek
  66. Harness**, dsh-TUI is the first.
  67. Featured by the **DeepSeek Harness official WeChat account**, listed in the
  68. [dshfind](https://dshfind.com/en/plugins/ccch1mneyyy/dsh-TUI) plugin
  69. directory, and ranked **#7 on [GitHub Trending](https://trendshift.io/repositories/146168)
  70. daily** (TypeScript).
  71. <div align="center">
  72. <table>
  73. <tr>
  74. <td align="center" valign="middle" width="50%">
  75. <img src="screenshots/wechat-official.png" alt="dsh-TUI featured by the DeepSeek Harness official WeChat account" width="480">
  76. <br>
  77. <strong>Featured by the official WeChat account</strong>
  78. </td>
  79. <td align="center" valign="middle" width="50%">
  80. <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>
  81. <br>
  82. <strong>Listed in the dshfind directory</strong>
  83. <br><br>
  84. <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>
  85. <br>
  86. <strong>GitHub Trending Daily #7</strong>
  87. </td>
  88. </tr>
  89. </table>
  90. </div>
  91. ## Quick Start
  92. ### Windows one-click installer (x64)
  93. Download `dsh-tui-setup-win-x64.exe` from [Releases](https://github.com/ccch1mneyyy/dsh-TUI/releases) and run it. Per-user, no administrator, fully offline, and no preinstalled Node or DSH.
  94. ### Command-line installation
  95. Prerequisites: [Node.js](https://nodejs.org/en) and
  96. [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness).
  97. The `deepseek-official` API-key route needs `DEEPSEEK_API_KEY`. On DSH
  98. 0.2.0-rc.1+, the standard profile can instead use `/auth login deepseek-account`
  99. and select the separate account route through `/model`. Other supported
  100. accounts can sign in through `/provider` or `/auth` after startup.
  101. The primary compatibility target is DSH `0.2.2-rc.3`. This adapter supports its
  102. Shell API, V4 session messages, declarative presets, and profile-backed settings;
  103. older supported hosts retain their compatibility paths. See [configuration](docs/configuration.en.md).
  104. DSH account notices use the existing account card. A notification with complete
  105. coupon metadata keeps the coupon presentation; otherwise the card shows the
  106. server's title and message without inventing an amount. The card refreshes its
  107. language and follows the server's display deadline. Enter or Esc dismisses it;
  108. account-page actions point to the official DSH account page and are not executed
  109. inside this TUI. Older hosts keep their original bonus API.
  110. On DSH 0.2.1-rc.2 and later, `/settings` also selects DeepSeek Search / Fetch APIs and edits their
  111. endpoint and result limits, supporting custom Loader entry IDs and a masked API
  112. key input saved through DSH's credential store. Official Flash model labels show the `1017` release
  113. marker while retaining the `deepseek-flash` model ID.
  114. `/settings` groups its sections into pages: the TUI's own settings sit under
  115. **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).
  116. On DSH 0.1.7, `/settings` uses the TUI's actual Loader entry ID, including custom
  117. IDs. It requires matching profile dependencies with `@deepseek-ai/schemastery`
  118. 3.18.3 or newer; an incompatible schema stops TUI startup with repair guidance
  119. instead of showing an uneditable settings page. Older hosts keep their legacy settings scope.
  120. The `dsh-tui` section of `/settings` is saved in `~/.dsh-tui/settings.json`, shared by
  121. every kernel; the first launch imports it once from the profile's `cordis.patch.yml` (and an older host's `~/.dsh/settings.yaml`)
  122. (see [configuration](docs/configuration.en.md#tui-configuration)).
  123. ```sh
  124. # Install the CLI and this plugin globally (ships the dsh-tui command)
  125. npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui
  126. # Start (first run auto-initializes the profile; needs pnpm)
  127. dsh-tui
  128. # Both `dsh-tui` and the short `dst` alias start the same TUI.
  129. dst
  130. ```
  131. Manual alternative: `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui`.
  132. The repo's `sh install.sh` runs that step and checks the required commands.
  133. Afterwards `dsh-tui` and `dsh --profile dsh-tui` are equivalent.
  134. > **New-user note**: pnpm ≥11 blocks dependencies with install scripts by
  135. > default and reports `ERR_PNPM_IGNORED_BUILDS`. Updates skip foreign-platform
  136. > natives — the `@img/sharp-*` packages and the Claude SDK's per-platform
  137. > bundles — so only this machine's binaries are fetched. `/update` and
  138. > `dsh-tui update` write both settings automatically. An update never installs
  139. > the Claude SDK on its own: it enters a profile only when you pick that
  140. > backend in the kernel picker, which then installs the pinned SDK for the
  141. > running platform. No manual step needed. Details:
  142. > [Getting started](docs/getting-started.en.md#pnpm-install-script-blocks-and-foreign-platform-natives).
  143. After startup the TUI checks for newer versions in the background. It never
  144. blocks the first frame. Type `/update` for a one-shot upgrade of the whole set
  145. — TUI, dsh engine and global launcher. It restarts automatically and resumes
  146. the current session, and refuses instead of leaving an incompatible or
  147. unbootable TUI/engine combination. Launcher alignment is normally best effort,
  148. but a failure after the engine advances blocks the restart and prints a repair
  149. command. If the registry has a newer dsh release outside the TUI's
  150. validated line, it says so and waits for a TUI update rather than installing an
  151. unvalidated engine. Launcher alignment only touches proven global installs;
  152. local npm/npx packages, ambiguous aliases and multi-member pnpm groups stay
  153. unchanged. See
  154. [Getting started](docs/getting-started.en.md) for the profile lifecycle,
  155. source builds, and troubleshooting, including migration from the former
  156. `dsh-cc-tui` package.
  157. `/restart` resumes the current session without installing anything. On
  158. non-Windows runtimes with `process.execve`, it and `/update` replace the
  159. current process, so repeated restarts do not accumulate waiting TUI processes.
  160. Other runtimes and kernel switches retain the supervised child-process handoff.
  161. A launch delegated to `dsh --profile` stays on that path until the next cold
  162. launch or kernel switch.
  163. ### CLI
  164. Automation: `dst -p "task"`, `dst run --json`, `dst session list --json`.
  165. The independent engine does not load the TUI or inherit its profile/preferences;
  166. it uses official DSH headless/services (validated on 0.2.0-rc.2, 0.2.1-rc.2, 0.2.1-rc.3, 0.2.1-rc.4 and 0.2.1-rc.5).
  167. `dst cli --help` lists its commands; `dst dsh <argv...>` forwards native DSH.
  168. See [Automation CLI](docs/cli.en.md) for protocol, limits, resume restrictions,
  169. and Node/Python/PowerShell integration examples.
  170. | Command | Purpose |
  171. | --- | --- |
  172. | `dsh-tui` / `dst` | Start the TUI; `dst` is a short alias for the same program |
  173. | `dsh-tui --resume [id]` · `dsh-tui update` · `dsh-tui doctor` | Resume a session · align the TUI, dsh engine and global launcher as one set · pre-flight environment checks |
  174. | `dsh-tui safe` | Read-only diagnostics, plugin inventory and repair guidance; `safe --rescue` builds a clean rescue profile |
  175. | `dsh-tui version` · `dsh-tui help` | Launcher and profile versions and usage; both work even without a `dsh` install |
  176. Leading DSH options such as `--dump-config` and `--patch <path>` are forwarded
  177. unchanged; other arguments go to the app in `dsh --profile dsh-tui`. Use
  178. `dsh-tui -- --resume=sid-1 ./notes` to send `--resume=sid-1 ./notes` as literal
  179. prompt text, without selecting a session or workspace. When invoking DSH
  180. directly, use `dsh --profile dsh-tui -- -- --resume=sid-1 ./notes`: the first
  181. `--` belongs to DSH, the second to the app. Host options can precede a literal
  182. prompt: `dsh-tui --patch ./overlay.yml -- --resume=sid-1` applies the overlay
  183. and sends `--resume=sid-1` as prompt text without resuming that session.
  184. Safe mode: [Getting started](docs/getting-started.en.md).
  185. ### Importing conversations from other agents (`dsh-tui migrate`)
  186. 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`:
  187. ```sh
  188. dsh-tui migrate # list importable counts per agent (writes nothing)
  189. dsh-tui migrate claude-code # import every Claude Code conversation (likewise codex / omp / zcode / grok-build)
  190. dsh-tui migrate codex --dry-run # preview what would land, write nothing
  191. ```
  192. - **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).
  193. - **Idempotent**: one deterministic UUID per source conversation — re-importing skips what is already present instead of stacking duplicates.
  194. - **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.
  195. In-TUI browsing: the session screen (`/resume`) shows a tab per agent that has conversations; picking one imports just that conversation and opens it.
  196. In-TUI: `/migrate` (optionally `/migrate <agent> [--dry-run]`) runs the same import in a child process and reports through the notification flow.
  197. CLI alternative: `dsh-tui migrate ...` from any shell runs the same import.
  198. With an installed `dsh` that supports host module resolution, both entries use its framework packages; a fresh profile does not need a separate copy. Dependency failures report their cause instead of asking for an update.
  199. Full guide: [Session migration](docs/migrate.en.md).
  200. - More agents (pi, opencode, …) extend the adapter registry as adapters land; grok-build reads `GROK_HOME` when set.
  201. **VS Code**: use the integrated terminal or the `dsh-tui-vscode` extension. See [VS Code guide](docs/vscode.en.md). **Herdr**: run `dsh-tui` in a [Herdr](https://herdr.dev) 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)](https://www.superlogical.com/rex/docs/build/program-status), 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.
  202. Bare `--resume` (`-c`, `--continue`) reopens the last session of the backend this
  203. launch selected. Startup recovery only ever targets that backend: a backend with no
  204. last session, or a derived target that belongs to a different backend than the one
  205. that actually booted (an unknown backend id falling back to DSH, `--backend` naming
  206. a backend that is not installed, a remembered kernel that is not the marker's
  207. source), refuses with a clear error and exit code 1 — never a silent cold start,
  208. never another backend's session, never a new session. An explicit `--resume <id>`
  209. passes that id to the selected backend as-is. The one exception is safe mode's
  210. "retry normal startup": it retries the kernel and session recorded in
  211. `last-run.json`, so a record whose backend is gone degrades to a warning plus a cold
  212. start — that retry is the last way back.
  213. ### Experimental: Claude backend
  214. dsh-TUI can also run its session on Claude: the same interface, driving the
  215. Claude Code CLI through the Claude Agent SDK. Your project's `CLAUDE.md`,
  216. settings, hooks, MCP servers and plugins load as the CLI loads them.
  217. ```sh
  218. # once, in the dsh-tui profile directory (the SDK is an optional dependency)
  219. cd ~/.dsh/profiles/dsh-tui && pnpm add @anthropic-ai/claude-agent-sdk@0.3.287
  220. dsh-tui --backend claude # or pick Claude in /kernel; that choice is remembered
  221. ```
  222. The easiest install: open the kernel picker (the launchpad "Kernel" entry or
  223. `/kernel`) and press Enter on the dim Claude row — the wizard locates the
  224. profile directory and installs the pinned SDK for you; the command above is
  225. its manual equivalent.
  226. An existing Claude Code CLI, including a Homebrew installation, still needs
  227. this SDK. If the SDK is unavailable, the row retains the detected CLI version
  228. and says "SDK unavailable"; press Enter to install the SDK in the profile.
  229. The confirmation shows the exact package and version. Closing the wizard,
  230. including clicking outside it on the launchpad, cancels a pending installation.
  231. - **Sign-in**: a `/channel` relay profile, your dsh-auth `anthropic` sign-in
  232. (`/login`), `ANTHROPIC_API_KEY` or cloud-provider variables, or an existing
  233. `claude login`, in that order. A `claude` on `PATH` is used when present, then
  234. one in the native install directory under your home (`~/.local/bin`, or
  235. `%USERPROFILE%\.local\bin` on Windows); every candidate has to launch and
  236. report a version, and the SDK's bundled binary is used only when none does.
  237. - **Works**: streaming, tool cards, approvals and questions, `/model`,
  238. `/effort`, Claude's permission modes (`/permission`, `Shift+Tab`),
  239. `/compact`, `/context`, `/mcp`, `/resume`, `/fork`, double-`Esc` rewind,
  240. subagents, background jobs, images, `/btw`, and the USD cost Claude reports.
  241. - **Not available**: DSH-only commands such as `/tree`, `/preset`,
  242. `/provider`, `/workspace`, `/agentview` and `/bg`. One process runs one
  243. backend; `/kernel` switches by restarting into a new session.
  244. - **Startup**: the screen appears before the session opens, with only a light
  245. profile composed (this package plus the profile's third-party plugins); see
  246. [Claude backend](docs/claude-backend.en.md#known-limitations). The DSH kernel
  247. starts from the same entry and loads DSH in the same process behind its first
  248. screen; `DSH_TUI_HOST_ENTRY=0` restores the old launch path for every kernel.
  249. Details and known limitations: [Claude backend](docs/claude-backend.en.md).
  250. ### Experimental: native Codex backend
  251. Run your own Codex through `codex app-server`, sharing its configuration,
  252. login, instructions, skills, hooks, MCP and native threads:
  253. ```sh
  254. npm install -g @openai/codex@0.160.1
  255. dsh-tui --backend codex
  256. dsh-tui --backend codex --resume <thread-id>
  257. ```
  258. Protocol baseline **0.160.1**, minimum **0.144.0**; other versions may show
  259. drift. `CODEX_EXECUTABLE` selects a binary; `/kernel` remembers the backend.
  260. `codex resume <id>` can open the same thread after the other writer exits.
  261. This is not `migrate codex`, which imports history into DSH.
  262. With native credentials, a writer conflict for an idle thread retained by the
  263. official background server triggers a reconnection to that server. Managed
  264. subscription credentials and `/channel` connections use private app-server processes.
  265. Streaming/tool cards, approvals, questions, steer/queue/interrupt, model and
  266. effort controls, Plan, `/review`, `/diff`, `/usage`, `/init`, skills and MCP
  267. share the existing UI. Async questions open the questionnaire while Codex
  268. continues working; answers steer the turn (or queue if unavailable), and
  269. dismissing the question leaves work running. **Shift+Tab only toggles Plan**, keeping its underlying
  270. permission preset; Full Access requires an explicit choice. Existing Codex
  271. settings are respected, not overwritten with defaults. `/login` offers
  272. ChatGPT OAuth, a device code or an API key (the last writes to Codex’s own
  273. credential store). Relay `/channel` connections take precedence; managed
  274. subscription tokens are only injected on first-party routes. dsh-TUI does
  275. not write `~/.codex/config.toml` or log out your native Codex account. A
  276. provider `env_key` from your own config (e.g. `DEEPSEEK_API_KEY`) that the
  277. shell did not export is injected from the DSH credential store when the ref
  278. is stored there — the active store first, then the default `~/.dsh` one — so
  279. keep the key in the store, no per-shell export needed. When nothing can
  280. supply it, the session still starts and the reason is reported once as a
  281. start notice: Codex itself rejects every turn of that provider.
  282. For Claude and Codex, `/channel` tokens (`CHANNEL_*` refs) belong to the
  283. active `DSH_HOME` only. Disconnecting a channel cannot revive a token from
  284. the default home; reconnect it in the active home if needed. Provider
  285. `env_key` credentials retain the fallback described above.
  286. TPS includes hidden reasoning time and excludes tool execution time. Live
  287. text estimates are corrected when Codex reports output token usage. Decode
  288. spans of 500ms or less are excluded from TPS samples; token and cost totals
  289. still include all reported usage.
  290. Native browsing/archive, fork/conversation rewind (the first message requires
  291. Codex app-server 0.160.1+), paged history, images,
  292. subagents, polled background terminals, goals and `/btw`/`/recap` use the
  293. existing surfaces. `/logout` removes only the matching dsh-auth credential;
  294. already-loaded managed tokens require a normal restart, not native logout.
  295. The real 0.160.1 app-server passed nine credential-free offline checks and eight
  296. daemon-resume checks, with no model turn or charge; real subscription login, credentialed model calls
  297. and real-TTY interaction were not run. Only Codex identification/title
  298. changes automatically, not palette or companion.
  299. Using ChatGPT subscription tokens in third-party clients is subject to
  300. OpenAI’s terms. Full instructions and current boundaries:
  301. [Codex backend](docs/codex-backend.en.md).
  302. ### DSH Agent Teams
  303. DSH Agent Teams lets the session's agent (the Lead) delegate to named
  304. subagents that share the working directory, message each other and coordinate
  305. on a shared task board. Since DSH `0.2.2-rc.2` it ships inside `dsh-base`:
  306. there is no plugin to install and no bundle to enable. It is off by default
  307. per root session — `/team on` enables it for this session and its whole
  308. subagent tree (the choice survives restarts), and `/team off` switches it off
  309. while keeping the subagents and the task board. `/team` (or `/team status`)
  310. reports the saved selection, the service and this session's subagents. When
  311. subagents are still running, `/team off` asks first (`/team off force`): they
  312. keep running — only the task tools and the Team guidance stop.
  313. Members are the root session's named subagents: `subagent` / `subagent_fork`
  314. take an optional `name` (the root is `lead`, descendants are paths such as
  315. `reviewer/checker`) and are the delegation tools — there is no
  316. `spawn_teammate` any more. The four `team_task_*` tools are the shared task
  317. board. Control tools address agents by name: `send_message({agent, message})`,
  318. `interrupt_agent({agent})`, `list_agents` rows `{name, status, description?}`,
  319. and `wait_agent` reports `{timedOut}`. Their calls and results render as
  320. one-line cards (`send_message` with its target and `sent`, `list_agents` with
  321. named rows), and a message between agents as a `✉ <sender>` bubble in the
  322. receiving session. The agents dashboard (Ctrl+A) and the agents side panel
  323. show a team view: the Lead line, members under their catalog name with
  324. `running` / `idle` status, the remaining subagents, a read-only task board
  325. (status, owner, `blocked`, write-scope warnings) and a banner when the team
  326. record was rejected. A root with Team off still shows its read-only board with
  327. a note, and an empty one falls back to the plain subagent view.
  328. An older DSH line (`0.2.2-rc.1` and earlier) mounts the retired experimental
  329. bundle instead, and TUI keeps that behavior there: the switch stays
  330. `/plugin enable|disable @deepseek-ai/dsh-experimental-agent-team-profile`
  331. (`/team` points at it; a launch without the profile plugin service gets the
  332. `dsh plugin --profile dsh-tui add <bundle>@<dsh-version>` CLI route), the
  333. durable roster comes from the projection, `spawn_teammate` is the delegation
  334. tool (with `subagent` / `subagent_fork` removed while it is present), and
  335. disabling the bundle while teammates run asks first. Those packages ship in
  336. lockstep with DSH and pin their peers exactly, so the version must match.
  337. Limits: on `0.2.2-rc.1` and earlier the switch covers the whole profile, not
  338. one session; there is no "enter teammate session" yet, and `/export` leaves
  339. team messages out. Upstream limits apply: teammates share one working
  340. directory, a team lives in one process, and a task owner is never released
  341. automatically. Upgrade every process that opens the same session store
  342. together: catalogs written by `0.2.2-rc.2` subagents cannot be opened by older
  343. DSH.
  344. A delegation provider whose settled runs fail at least twice and at least half
  345. the time gets one degraded-channel line above the agents list; the built-in
  346. `subagent` route, workflow members and per-type Claude children are excluded
  347. because there is no provider to switch to.
  348. Subagent failure badges and the Companion error state share session-scoped unread
  349. status. Opening that child’s detail or main view acknowledges only that failure;
  350. a new run or failure alerts again. Acknowledgements survive panel remounts and
  351. session switches during this process, but a cold restart starts unread. Opening
  352. the dashboard alone does not acknowledge every child. Task status stays failed.
  353. ## Keybindings & Mouse
  354. `Enter` send · `Tab` complete · `Ctrl+Enter` interrupt and send · `Alt+Up` recall the last message · `Esc` closes local layers before interrupting a running turn, double-`Esc` rewinds on empty idle input · `Ctrl+B` side panel · `Ctrl+O` details · `Ctrl+R` history (`↑`/`↓` and `Ctrl+R` are scoped to the current project) · `Ctrl+V` paste · `Ctrl+Shift+E` fullscreen draft editor · `?` shortcuts · `←` open the session manager (DSH backgrounds the current session first).
  355. In both the launchpad and chat, `Ctrl+U` deletes from the caret to the current line start, preserving text to the right and whole image chips. It edits only the focused input.
  356. In the launchpad input, `Shift+Enter` (or `Option+Enter`) opens chat and inserts a newline at the caret, keeping the draft and staged images unsent. Continue typing there, then press `Enter` to send.
  357. In both the launchpad and chat, `Alt/Option+←/→` moves by whitespace-delimited words and `Alt/Option+Backspace` deletes the previous word, like `Ctrl+W`. On macOS, configure your terminal to send Option as Meta.
  358. Use `Alt+Up` / `Alt+Down` to page through question text and details, or approval previews on very short terminals, without moving the choice focus; these keys are remappable in `/settings` → `Shortcuts`. Fullscreen also supports the wheel over the preview. Complete OAuth links remain readable when browser and clipboard helpers are unavailable. Fixed-action permission questions offer only the caller's choices; ordinary questionnaires still accept free text.
  359. Text, cursor position and staged image attachments on the launchpad or in chat while the backend starts are preserved when the session becomes ready. Press `Enter` after it is ready to send; an earlier `Enter` preserves the draft without queuing it. Opening a new session while startup is pending clears the previous draft and its images.
  360. The goal bar stays on one summary line: hovering truncated goal text in fullscreen or split shows the whole objective, and a bare `/goal` prints the full status — objective, phase, rounds or budget, available commands — as a transcript block in the `/plugins` shape. Inline mode sees no pointer events, so that block is how its users read a long objective.
  361. While the model is working: `Enter` steers, `Tab` queues a follow-up, `Ctrl+Enter` interrupts and sends. Input that names a command is still a command — with or without arguments — so `/model` or `/new` reach their own gate (and the `/` overlay sinks the commands that affect the running conversation) instead of silently becoming an interruption; only text that is not a command — and a direct skill gesture such as `/skill-name …` — steers.
  362. When DSH ends a turn because its session was disposed, the transcript shows “Session stopped”; user interruption keeps its existing prompt for what to do next. This describes the reported stop reason and does not recover a stuck session or its queued inputs.
  363. Windows Neovim/Vim terminals identified by `NVIM` or `VIM_TERMINAL` retain VT input instead of enabling ConPTY mode 9001. For another incompatible embedded host, set `DSH_TUI_DISABLE_WIN32_INPUT_MODE=1` before launch (PowerShell: `$env:DSH_TUI_DISABLE_WIN32_INPUT_MODE="1"`). The same gate applies at startup and after resume. Native Windows Terminal, conhost and VS Code keep their existing mode unless disabled; the opt-out can remove modified-Enter reporting.
  364. Extended key reporting (Kitty keyboard protocol and xterm `modifyOtherKeys`) is enabled for a fixed terminal list: iTerm2, kitty, WezTerm, Ghostty, rio, Orca, tmux, Warp and Windows Terminal. A terminal missing from that list can opt in with `DSH_TUI_FORCE_EXTENDED_KEYS=1`, and `DSH_TUI_DISABLE_EXTENDED_KEYS=1` opts an allowlisted terminal back out for SSH or nested xterm.js hosts (it wins when both are set). Outside native Windows, where win32-input-mode reports Enter's modifiers instead and is not touched by this switch, a terminal without extended keys cannot tell `Shift+Enter` from `Enter`, and `Ctrl+J` is the newline fallback.
  365. 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.
  366. Incomplete records are held for a bounded recovery window (1 second from first capture, never extended by later input; 64 bytes max); past either bound the hold ends and input is handled as before. Unrecognized complete CSI sequences are not inserted as text; after a damaged CSI prefix, a bare ASCII letter can be consumed as its terminator, while normal Win32 key records and bracketed-paste text retain their own boundaries.
  367. A session's very first record can still leave residue if it is split before its record-specific shape forms; once any record has been decoded, every split position is covered. Inside the recovery window, literal input starting with `[digit;…` cannot be told apart from a protocol prefix — it may be held, or re-joined to a preceding `Esc`. To type it, wait for the window to close, or avoid that shape right after `Esc`.
  368. Terminal replies that arrive split are reassembled the same way (native Windows ConPTY is the common source): while the app still has a query awaiting its answer, an unfinished DA1 / DA2 / DSR / DECRPM / XTVERSION tail — even one split again after the introducer `Esc` was flushed — is held across input delays, but only while its shape can still complete into the response type that query expects. It is then consumed as the reply it completes instead of entering the prompt as protocol text.
  369. That claim is evidence-gated, and this is the difference from earlier builds: no query awaiting an answer means nothing is claimed, so a literal `[?61;4c` typed right after `Esc` still enters the prompt exactly as before.
  370. The window is bounded like the record hold (about a second, never extended by later input; 64 bytes max); past either bound it ends, and bytes still shaped like an unfinished reply prefix are dropped rather than shown.
  371. Inside that window, with a query of the matching response type outstanding, same-shaped literal input can still be claimed as a reply; to type it, wait for the window to close (about a second), or avoid that shape while a query is outstanding.
  372. Fragmented SGR mouse reports no longer land in the prompt as text: an incomplete report header is held until the rest arrives, and a report that completes is handled as a mouse event. The hold is armed only while mouse reporting is actually active (fullscreen, with mouse tracking enabled); inline sessions and terminals that never enable tracking keep the existing behavior. The claim window is bounded from first capture (at most 1 second; 64 bytes max), and a continuation arriving inside it is still claimed rather than replayed. Release has no timer: once a parse call sees either bound exceeded, it replays the held bytes as ordinary keys in arrival order — literal input can be delayed, but is never dropped.
  373. A completed text-only assistant reply containing only a leading `⏵` status line remains visible in the conversation and can be selected for copying. Live status lines and status lines followed by a real answer stay out of the transcript body.
  374. Plugin slash-command results, including errors, remain as local transcript blocks for scrolling and copying during the current session. Indentation and line breaks are preserved. Each report retains at most 200 lines, 65,536 UTF-16 code units and 4,000 terminal cells per line, plus a visible truncation marker. The local display rows are not sent as model input or replayed as conversation history. The backend may separately persist command audit events and their results. Older local report blocks are evicted within the shared 600-row budget. Explicit built-in report layouts (such as `/goal`) keep their existing formatting.
  375. 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.
  376. Automatic copies keep the text selected; press `Esc` to clear it or start a new selection to replace it. Selection highlighting skips trailing padding and blank rows while preserving spaces within text and code indentation. Inline mode uses the terminal's native selection.
  377. While holding a fullscreen text drag, use `PgUp` / `PgDn` or the wheel to extend the selection across pages: its origin follows the text while the other endpoint stays at the pointer. After release, both endpoints follow scrolling. Fully off-screen selections keep their captured text without highlighting unrelated edge cells; scrolling back restores their position and column range.
  378. When a fullscreen selection starts in a code block's body, soft-wrapped rows join without adding frame padding or newlines, in both light and full frames. Hard line breaks and the existing hard-line inset remain part of screen copying.
  379. During a fullscreen text drag, the native cursor follows the selected text's edge using your terminal's enabled cursor animation or trail effects. Moving into trailing padding or blank rows keeps it at the nearest selected text edge. Releasing or cancelling the drag restores the focused input's caret.
  380. File paths in prose can open the file-action menu; automatic detection does not extract a path from inside a slash-delimited token such as `working/idle/needs-input` or a date such as `2024/01/15`. On Linux a handler marked `Terminal=true` (for example `vim.desktop`) opens inside a terminal (for example `kitty -1 vim <file>`); other targets still go to the system default handler. This wrapper does not support non-empty `Path=`: those entries stay with `xdg-open`. Its generic path can still lack a TTY and ignore the working directory, so such terminal handlers may still fail to open.
  381. **Pasting**: the launchpad accepts clipboard images and pasted image paths as `[Image #N]` attachments; `Enter` sends them with the first message. Commands that do not accept images preserve the draft and its attachments. Image chips behave like chat: arrows step across them, Backspace at the end or Delete at the start removes the whole image, and Ctrl+W never splits a chip. Text pasted on the launchpad is folded to one line. In chat, native and bracketed paste keeps ordinary text and newlines, and never submits itself on arrival. On Windows terminals that deliver a paste as win32-input-mode key records, a record stream leaked into the payload is decoded back into the characters its `Uc` field encodes — newlines included — so the composer's line count matches what was pasted; only records with no character meaning are stripped (a multi-line paste no longer leaves stray `_`), and a complete record is always consumed before an ESC-less tail, so no payload character is deleted along with an orphan escape. Pasted CRLF collapses to a single newline; genuine underscores and bracketed-paste text are untouched.
  382. **Dropped files**: a native Windows desktop drop (Windows Terminal / OpenConsole) arrives as an OSC 8 hyperlink; the parser restores its `file://` URI to a decoded local path before paste hygiene runs, so the `]8;id=…;` parameter bytes never reach the draft. Image paths enter the existing image staging pipeline; other files are inserted as a referenceable path (a path containing whitespace arrives in the composer's quoted `"…"` single-token form). Only `file://` URIs are restored, and it is fail-closed: a remote authority/UNC, a payload carrying several distinct URIs, or a URI that carries several tokens is refused and stays literal text rather than guessed.
  383. Fullscreen drag-copy uses the final highlight. If a live row changed during a drag,
  384. move the selection back to stable text to establish a new baseline. A stationary
  385. selection whose copied text changes is still refused; automatic scroll/resize
  386. does not clear that protection.
  387. The pixel whale, large title and context/TPS colors follow the same terminal color depth as other text: monochrome, 16-color, 256-color or truecolor. Apple Terminal and tmux use the shared fallback; `NO_COLOR` and `FORCE_COLOR` retain the existing shared color policy.
  388. If resume reports that another DSH process owns the writer, release the session in that process (for example, dsh web) and retry in the same TUI. The foreground session stays intact; do not delete session or lock files to bypass single-writer protection.
  389. Full reference: [Interaction and commands](docs/interaction.en.md).
  390. ## Built-in Commands
  391. `/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` `/setup` `/status` `/cost` `/jobs` `/skills` `/mcp` `/provider` `/auth` `/login` `/update`.
  392. On DSH, `/fork` keeps the current session open and creates a resumable copy; a copy with history records its parent and appears in the same session family.
  393. `/dsh`, `/codex`, and `/claude` switch directly to the named kernel, just like choosing it in `/kernel`: the choice is remembered and the process restarts into a new session. A running turn blocks switching; choosing the current kernel keeps the session. Availability checks and the Claude install wizard follow the same picker flow.
  394. `/model` shows models and reasoning effort on one page. DSH has provider tabs with **Recently used** first, moving the current model to the top; `Tab` / `Shift+Tab` select the next / previous provider. Codex and Claude open their model catalogs directly, without provider or recents tabs. `↑/↓` select a model, `←/→` adjust its effort, `Enter` applies the model and any explicit effort draft, and `Esc` cancels. Changing only the model preserves the backend's preference handling. Mouse users can click the available tabs, models, effort levels, and select/cancel hints; clicking an effort level immediately applies the focused model and that effort and closes the picker. The wheel moves through models.
  395. Short terminals keep the focused model and select/cancel actions visible, hiding descriptions and neighboring models first, then the effort row when only two rows remain.
  396. Shortcuts sit below the title and effort levels have their own section; DSH, Claude, and Codex use the terminal background while covering the text underneath.
  397. In `/provider`'s model list, focus a model and press `Tab` to edit its context window, max output tokens, reasoning efforts, and image input capability.
  398. The session manager focuses the most recently used session in the current workspace; if there is no history, it focuses the new-session card. Moving between the workspace rail and session list preserves the selected session, including when the mouse enters the list. Switching to another workspace selects its latest session; switching back also starts from its latest session instead of restoring an earlier selection. Press `←` to move to the workspace rail. DST preloads the session list in the background after startup and updates the cache on success. The manager paints the last successful list immediately. Opening `/resume` while that read is pending shares the request and receives results that have already arrived. This first-paint snapshot survives restarts on DSH, Claude and Codex and is isolated by backend and storage directory. With or without a snapshot, all three backends prioritize the current workspace before filling in other workspaces. Fresh sessions and titles merge into the list immediately; cached rows from other workspaces remain until the full read finishes. Background updates preserve a session the user has selected manually. Claude and Codex first request up to 32 recent sessions within their native cwd scope: Claude's SDK includes Git worktrees in the same repository, while Codex matches the session cwd exactly. Codex listings reuse the running connection and read the first 32 regular results alongside the state DB shortcut, then fill in later pages. The browser groups sessions by their own cwd. DSH resolves the current workspace's metadata first and publishes it before reading other workspaces' logs, even when it has fewer than 32 sessions. Titles that require a deeper DSH log scan appear first with a fallback name and update in place when recovery finishes.
  399. The session manager shows the selected workspace's absolute path once, beneath the source tabs (wrapping when needed; hover reveals exceptionally long paths). Session rows show their title and essential status/time instead of repeating the directory; DSH size and model remain in the title tooltip.
  400. With DSH's current JSONL backend, startup and `/new` keep initial permission events in memory until further session activity saves the complete log. Flushing a session that holds only initialization leaves it unstored. Restarting an unstored empty session starts fresh.
  401. The project rail uses one line per directory on every backend and source tab; the selected project’s path appears once above the panes.
  402. Removing a workspace registration keeps its sessions accessible under a "History only" directory in the rail.
  403. History-only directories offer edit and new-session actions; rename and remove are available for registered workspaces.
  404. If a `/resume` attempt fails or is cancelled before switching, it releases any session occupancy acquired by that attempt so the session can be retried.
  405. On Linux, stale TUI occupancy and mount locks can be reclaimed when the old PID
  406. has been reused by a non-leader thread. This requires readable `/proc` identity
  407. data in the same PID namespace; uncertain identities remain occupied. Reuse by
  408. another process can still retain a stale claim, so this is not a general fix for
  409. PID reuse across platforms.
  410. **Background jobs**: card headers open the focused task panel. Click the card body or use `Ctrl+O` to toggle the command between its first statement and full script. Commands and output use separate colored edges with `❯` (`>` on Windows) and `≡` on their first rows; output always stays at the latest two visible rows. `/jobs` and the side panel keep the full output scrollable, while `e` toggles the focused command. Consecutive blank script lines collapse to one.
  411. **Background sessions**: On the DSH backend, `/bg` or `←` on an empty prompt backgrounds the current session and opens the session manager; `Esc` returns to it. Background sessions run in this process and stop when the TUI exits. Logs survive. On Claude/Codex, those entries open the session manager without backgrounding the session.
  412. Full commands: [Interaction and commands](docs/interaction.en.md).
  413. ## Configuration & Extensions
  414. Agent presets, themes, MCP servers, environment variables: [Configuration](docs/configuration.en.md) · [Themes](docs/themes.en.md).
  415. With the DeepSeek brand, Companion skins `deepy` and `whaleGirl` replace the maid portrait; choose `whale` and enable Maid portrait to use it. Claude uses its own artwork; Codex uses its own raster portrait or the maid character-art fallback. Both brands ignore these settings for splash artwork. See [Configuration](docs/configuration.en.md).
  416. DSH profiles inherit official reporting defaults: DeepSeek API requests carry plugin package identities and incremental Session logs to the configured `baseURL`, including third-party gateways, while OpenTelemetry uploads a Session-log prefix only after explicit feedback. User overrides remain supported; see [reporting settings](docs/configuration.en.md#official-request-metadata-and-feedback-reporting).
  417. ## How It Works
  418. ```text
  419. dsh profile → dsh-base → dsh-TUI Cordis patch → agent preset + DSH services
  420. → session/event → Channel projection → React components → Ink/Yoga renderer → terminal
  421. ```
  422. The TUI handles interaction and presentation. The session log is the source of truth. DSH services own models, tools, and persistence. Long sessions render in O(visible window).
  423. Runtime path, module boundaries, performance notes and persistence locations: [Architecture and limitations](docs/architecture.en.md).
  424. ## Known Limitations
  425. - Fuzzy `@` completion refreshes on the next query after its 2-second cache expires; a menu left idle does not poll for changes. Path-shaped queries such as `@src/` read that directory directly. The existing 100-file/100-directory scan budgets still apply.
  426. - Injected plugin context has no standalone display; it counts into the context segments.
  427. - `/model` changes the next request’s route in the same session; history and session ID are preserved. The last used route is recorded when the next request starts. On DSH 0.2.2, API/plugin selections also update the next-model readout; late events from a previously fixed step do not overwrite the selected model's capacity metadata. DSH versions before `0.1.2-alpha.3` refuse switching and prompt an upgrade because their subagents inherit the original route.
  428. - `Ctrl+V` needs platform clipboard tools; unsupported bitmap formats are rejected.
  429. - Windows Terminal/ConPTY sixel frames check the last transmitted raster’s cursor position before parking, using measured cell geometry and encoded band controls. Detected drift uses the same physical clear and redraw as `Ctrl+L`. Probes allow one pending reply (500 ms), skip resize/handoff, and pause for 60 seconds after an unanswered query or three repairs within 10 seconds. Set `DSH_TUI_SIXEL_CURSOR_HEAL=0` to disable; `DSH_TUI_DEBUG` records probe/recovery decisions. This bounded mitigation cannot detect every kind of pixel corruption or repair ConPTY itself.
  430. - Shutdown drains only the actual renderer-owned input after terminal cleanup and a 150-ms settle window. Embedders retaining only `unmount` keep that input lease; wrappers replacing the method must pass the renderer’s `shutdownInput` lease to `finishExit`. Custom input drains its own buffered bytes; a device-specific kernel drain can be supplied as the bounded synchronous `render({ drainStdin })` callback. Revoked/replaced owners and non-TTY input are not drained. The window does not guarantee arbitrary SSH latency.
  431. - Local Windows copying uses PowerShell with UTF-8 stdin. Copies run in order; each PowerShell attempt has a two-second timeout (Windows PowerShell, then PowerShell 7). If both fail, OSC 52 remains the fallback and requires terminal support. SSH never writes the remote native clipboard.
  432. - Catchable exits explicitly end synchronized output (DEC 2026) as part of terminal cleanup, even without a final frame. SIGKILL, native aborts and a fully blocked JavaScript event loop cannot guarantee in-process cleanup; recovery then requires the terminal or an external supervisor.
  433. - While the TUI owns an active raw input, it reasserts OS raw mode on input-gap/focus recovery and every five seconds without waiting for a key. This repairs externally reset cooked/ECHO state even when Node still reports `isRaw=true`; recovery may take one interval while the event loop runs. The periodic check stops during editor pauses and shutdown/handoff and does not resend display protocols.
  434. - A dropped file is restored from its OSC 8 `file://` URI alone: multi-file drops, non-Windows terminal drop encodings and terminator-less truncated frames are not covered, and the hyperlink's own display name is never used.
  435. - A background session lives inside this process and stops when the TUI exits.
  436. - `/thinking` is not persisted; the kernel `minimal` agent preset (极简模式, one persistent-shell tool) mounts no compaction and does not prune tool results — a long session can hit the context limit, oversized tool output stays in the context in full, and `/compact` plus the questionnaire are unavailable under it (Help and `/` completion mark the entry, and entering the preset says so once); that is a different thing from the `/settings → Minimal UI` (极简界面) display switch; `/update` needs a `dsh --profile` launch and is refused while a turn is running.
  437. - The status-bar `≈¥` and `/cost` are session estimates that include subagent usage (priced per each agent's model × peak/idle × cache components); unofficial or unlisted models show tokens only and are marked unpriced. **The platform bill is authoritative.**
  438. - Fragmented SGR mouse reports are covered at the mechanism level with controlled fixture comparisons; the reporter environments (macOS → SSH, WSL2 with `dsh web`) have not been re-tested.
  439. Full list: [Architecture and limitations → Known limitations](docs/architecture.en.md#known-limitations).
  440. ## Development
  441. `pnpm dev` keeps the full install/build/pack checks by default. For explicit local
  442. iteration, set `DSH_TUI_DEV_FAST=1` (for example,
  443. `DSH_TUI_DEV_FAST=1 pnpm dev -- --no-launch`). A miss runs frozen install,
  444. `compile`, pack without repeating `prepare`, and isolated profile installation.
  445. An unchanged hit skips all four stages only while source/config and compiler-loader contents,
  446. Node/pnpm/npm/dsh versions, compiled and vendor output, the tarball, and the installed
  447. package/profile match. Replacing pnpm/npm/dsh without changing its reported version
  448. requires one normal (non-fast) development run.
  449. Internal document links such as `CLAUDE.md -> AGENTS.md` are fingerprinted;
  450. external, excluded, dangling or cyclic links and unreadable inputs disable reuse
  451. with a diagnostic. Failures invalidate the success stamp before work begins.
  452. The script prints stage durations and cache hits. Run normal `pnpm build` and
  453. focused regressions before publishing; fast mode does not change release gates.
  454. The monorepo development host (`pnpm tui`, `scripts/run.ts`) enables heap
  455. forensics only with `DSH_TUI_HEAP_WATCH=1`; unset it or use `0` to disable it.
  456. It samples every 15 seconds and takes one snapshot at each heap threshold of
  457. 1024, 1536, 2048, 2560 and 3072 MiB. Its own completed files in `$DSH_HOME`
  458. retain at most four 64-KiB logs and two snapshots totaling at most 1024 MiB.
  459. `DSH_TUI_HEAP_MAX_MB` changes the snapshot budget (integer 1–16384; invalid
  460. values use 1024). A single oversized snapshot is removed too; the latest
  461. diagnostic may therefore be a log only. Snapshot creation still blocks and
  462. uses extra memory and temporary disk space; this does not fix memory leaks.
  463. Files use a process-unique `dsh-tui-heap-watch-` prefix. Manual/legacy files
  464. are untouched; incomplete `.writing` files are removed only after their
  465. owner PID is confirmed absent. Live or uncheckable owners are preserved,
  466. and cleanup failures are nonfatal, so quotas apply to successful cleanup of
  467. completed files, not peak usage or uncertain crash leftovers.
  468. CI uses Node 24 and pnpm 11. The package supports Node `^22.19 || >=24`.
  469. The launcher checks the manifest’s Node range before loading the application. Known unsupported versions (including Node 23 and prereleases) stop with Node upgrade instructions. Missing or unrecognized ranges allow startup for compatibility with migrated launchers; `doctor` reports that compatibility cannot be determined. `help` and `version` remain available.
  470. TUI entry points use production React even when the workspace sets
  471. `NODE_ENV=development`. For renderer debugging, explicitly set
  472. `DSH_TUI_REACT_DEV=1` (for example, `DSH_TUI_REACT_DEV=1 pnpm dev` or
  473. `DSH_TUI_REACT_DEV=1 pnpm tui`). This selects development React before it
  474. loads; its render instrumentation can accumulate memory in long sessions.
  475. ```sh
  476. pnpm install --frozen-lockfile
  477. pnpm build
  478. pnpm smoke
  479. ```
  480. `lib/types/` is ignored generated output. `pnpm build` recompiles it from a
  481. clean output directory and runs the build gates. **Git URL installs are not
  482. supported.** The source manifest keeps `@dsh-std/*` as workspace deps and
  483. `vendor/dsh-std` as a submodule. pnpm ≥11 also refuses git-hosted `prepare`
  484. scripts by default. Install the registry package instead:
  485. `dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui`. Rendering,
  486. questionnaire, or tool-card changes also need the matching regression scripts.
  487. ## Plugin Ecosystem
  488. Plugin development: [admission & development guide](tui-profile/docs/plugin-admission-and-development.md) · [plugin-template](https://github.com/dsh-tui-ecosystem/plugin-template) · [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem). Reference implementation: `dsh-working-activity`.
  489. Exported plugin subcomponents are admitted using the nearest package manifest of their ESM entry, including import-only and conditional exports; they do not inherit an outer package's identity.
  490. A backend plugin (the `tui.dsh/v1alpha1` `Backend` contribution family) is in the kernel picker after a restart: the boot scans the bundles the profile declares, admits and registers each package-root `dsh-plugin.json` declaration, and reads the implementation from the package's `backend` export — importing that module only when the backend is actually selected.
  491. Each bundle may declare one backend, and its handler id must match the declaration. Entries awaiting authorization are neither probed nor loaded, including when explicitly requested at startup.
  492. Seam grading and API notes: [Plugin development](docs/plugins.en.md). The organization maintains the listing only; it does not endorse community plugins.
  493. Installing a plugin from inside the TUI: `/plugin install <package | path | git url>`. It goes through the host's profile plugin manager — a pre-install notice, a trust confirmation, cancellable progress, build-script approval and exact-version exemptions. Packages on the first-party feed this package ships (`tui-profile/feed/first-party.json`, pinned per release and decided offline) skip the trust confirmation, and only a spec that names that exact version qualifies: a bare name, a tag or a range is resolved again at install time, so it is confirmed with the person instead. What was confirmed is what gets installed — the run pins the exact `name@version` the inspection read — and a turn that is still running refuses the install (finish it, or `/new`, first). The same actions remain available from the CLI (`dsh plugin --profile dsh-tui …`). The confirmation lists the permissions the package declares; `Enter` installs **and grants** — the grant is written to `~/.dsh-tui/extension-grants.json` before the install starts, and a failed install rolls that write back. A registry package's declaration cannot be read before it lands, so a `grant` step follows a successful install: `Enter` grants, `Esc` skips (the install stays). Declared permissions this host does not know are skipped and named. On a terminal too short for a permission row, the list folds to a count or the key hint carries the count; the package identity, the notice and the keys stay visible.
  494. A spec names one of three things:
  495. ```sh
  496. /plugin install /path/to/repo
  497. /plugin install https://github.com/exam/ple.git
  498. /plugin install @scope/package@1.2.3
  499. ```
  500. Typing `/plugin install ` lists these three shapes in the completion popup, and the same shapes follow the installed names on `/plugin info `. They are examples, never candidates: `Tab` leaves the draft exactly as it is, and `Enter` runs the line you typed — the subcommand's usage line while the spec is still empty, your own spec once it is not. No example can therefore be inserted or installed by accident, and a real path that merely starts like one is never swallowed.
  501. During installation, `esc` attempts cancellation and keeps the pane open until the write settles; if cancellation is too late, it waits for the installation to finish. During exemption registration, it waits for the current write and stops subsequent grants and the retry. Exemptions already written remain.
  502. Failed installs show up to six redacted log lines; lines larger than 16 KiB are omitted with a notice.
  503. Managing what is installed: `/plugin remove <bundle>`, `/plugin enable <name | row id>` and `/plugin disable <name | row id>`. A bundle is a composition layer and a row is one patch entry, so the two are separate actions, and a bundle name is matched before any row identity. A module name shared by multiple rows requires a specific row ID. **Gate 2 refuses the three ways this app could switch itself off** — removing or disabling the bundle that provides it, the host layer `dsh-base`, or one of its own rows — and says which rule it broke, without calling the service at all; that holds whether or not hot reload is live, which is the path the host's own guard misses. `enable` is never refused by gate 2 (it is the repair action). Every enable and removal asks first; `disable` asks only about a host-layer row. The host does not attest installed package sources, so even an exact feed match requires confirmation before enabling.
  504. These three actions have no cancellation — the service offers none — so `esc` only closes the pane while the write finishes and reports itself into the transcript. Enable and disable have no CLI verb either (the service writes them into the profile's own files). **Grants follow the lifecycle**: `enable` enables and grants the declared permissions, `disable` disables and revokes the permissions that component declared, and `remove` **deletes the component's `grants`/`denies` entries** after the removal — grants are keyed by component id, so leaving them behind lets any later package reusing that id inherit them silently; a reinstall asks again. Backend data directories, storage namespaces and the effect ledger stay, and the residue report names each source by its path. A failed grant write never blocks an install or enable — it is reported instead. Grants are behavioural constraints, not a security boundary.
  505. `/plugin list` also advertises the experimental features DSH ships, leaves off by default, and this app knows how to drive (currently Auto review, Session search and Git worktrees), each with its switch and usage line. A DSH installation that does not ship one shows no such section. Agent Teams is no longer one of them: `0.2.2-rc.2` builds it into `dsh-base`, so it is switched per session with `/team on|off` instead of a bundle.
  506. ## Documentation
  507. - **Start** — [Getting started](docs/getting-started.en.md) · [VS Code](docs/vscode.en.md)
  508. - **Use** — [Keys and commands](docs/interaction.en.md) · [User guide](docs/user-guide.en.md) · [Themes](docs/themes.en.md)
  509. - **Configure** — [Configuration](docs/configuration.en.md)
  510. - **Internals** — [Architecture and limitations](docs/architecture.en.md) · [Session mounting](docs/session-mount-runtime.en.md)
  511. - **Plugins** — [Admission and development](tui-profile/docs/plugin-admission-and-development.md) · [Seams](docs/plugins.en.md)
  512. - **Contribute** — [Contributing](docs/contributing.en.md) · [Roadmap](docs/roadmap.en.md) · [Community](docs/community-management.en.md)
  513. Everything, bilingual: [docs/README.md](docs/README.md).
  514. ## Community
  515. - **Ecosystem organization**: [dsh-tui-ecosystem](https://github.com/dsh-tui-ecosystem)
  516. hosts community plugins, templates, and the curated list. Come ship a
  517. plugin, pitch an idea, or just hang out 🐋
  518. - **Chat groups** (Chinese-language): usage questions, plugin ideas, and
  519. feature wishes are all welcome.
  520. - **Code of conduct**: please read the
  521. [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.en.md) before taking
  522. part.
  523. | WeChat group (dsh-TUI community 4) | QQ group (ID 572549239) |
  524. | :---: | :---: |
  525. | <img src="screenshots/wechat-group.jpg" alt="dsh-TUI community WeChat group 4 QR code" width="200"> | <img src="screenshots/qq-group.png" alt="dsh-TUI community QQ group QR code" width="200"> |
  526. > The WeChat QR code expires roughly every 7 days; if it stops working, use
  527. > the QQ group (572549239) or open an issue to nudge us for a refresh.
  528. ## Permissions and Security Boundary
  529. > **Windows security warning:** the Windows profile defaults to `danger-full-access` with approval set to `never`, so tools have unrestricted access. Inspect and tighten the profile before starting next to sensitive credentials or in an untrusted repository.
  530. No sandbox of its own: dsh-TUI uses the active DSH profile's filesystem, shell, sandbox and approval policies. Permission presets come from the DSH `permissionPresets` registry.
  531. **Permission persistence** (all three backends): the Claude and Codex backends keep their `/permission` picks in `~/.dsh-tui/backends/<id>/prefs.json`; the DSH pick is kept at `~/.dsh-tui/permission.json`. Every durable preset switch teaches it (picker, typed `/permission`, Shift+Tab static modes, or a switch the official command performed on its own), and a session that never customized its permission planes starts on the remembered preset — applied through the same official switch path. "Never customized" is about the user: the composition writes its own default preset into every fresh session at creation, and those events do not count. Plan-mode transients and the experimental Auto review preset (see below) are excluded, a `DSH_PERMISSION_MODE` launch pin (this run's initial permission plane) outranks the file, and an identity the mounted roster no longer offers is skipped.
  532. **Auto review** (DSH, experimental): `/plugin list` advertises it; after `/plugin enable @deepseek-ai/dsh-experimental-auto-review`, the `auto` preset (shown as "Auto review", tagged `EXP`) appears in `/permission` and its completions live, and disappears when the plugin is removed. It is session-only: the model reviews every tool call before it runs, there is no file sandbox, and each call costs one extra model request; its approval prompts show the localized reason, and a subagent denial reads "Auto review denied; not executed". Picking it in the picker first shows a risk confirmation (`Enter` enables, `Esc` goes back; in fullscreen its Enable / Go back rows are clickable); a typed `/permission auto` switches directly. Once the current session has selected it, the picker skips the confirmation and Shift+Tab stops skipping it.
  533. **Session search** (DSH, experimental): `/plugin list` advertises it; after `/plugin enable @deepseek-ai/dsh-experimental-session-search`, an agent gains five read-only tools (`session_search`, `session_event_search`, `session_trace`, `session_event_trace`, `session_event_read`) over earlier sessions in the same workspace — cross-session access requires an identical `cwd`. The index is in memory and is built on the first search; nothing is written to disk. This app keeps the kernel Minimal preset at its single persistent-shell tool, so Minimal never shows these five tools or their usage guidance.
  534. **Git worktrees** (DSH, experimental): `/plugin list` advertises it; after `/plugin enable @deepseek-ai/dsh-experimental-tool-worktree`, an agent gains `create_worktree`, which creates a new Git branch and a checkout under `.agents/worktrees/<name>` of the current repository (from `HEAD` or a local revision; uncommitted files stay in the source checkout) and moves the session into it — the status line, Git branch and `@` completion follow, while the session stays registered under its project. Its card reads `Worktree("<branch>")` with the checkout path and base revision. Nothing is cleaned up: remove the checkout with `git worktree remove <path>` and the branch separately with `git branch -D <branch>` (the agent leaves with `working_directory`; once the checkout is gone, the next request returns the session to the project). A leftover branch makes a later `create_worktree` with the same name fail. Calling it from inside a worktree nests the new checkout under that worktree. Moving does not change file permissions or already-open terminals. This app hides `create_worktree` from the kernel Minimal preset and the bundled liangshen preset: their persistent shell (liangshen's on macOS and Linux) keeps the directory it started in, so after a move it would still edit the source checkout.
  535. **Upstream auto-retry** (DSH): whenever a session binds (boot, `/model` switch, resume), the TUI seeds a retry policy — 5 attempts, transport-drop-aware failure codes including `STREAM_CLOSED` (a dropped upstream stream) — on **the provider route that session actually uses**, through the official `llm-pi-ai` settings section (the policy the kernel's `llm-retry` plugin executes). Only routes without an explicit `retryPolicy` are seeded — dormant channels are never written — and `upstreamRetry: false` in cordis.yml opts out.
  536. Details: [Permissions and security boundary](docs/architecture.en.md#permissions-and-security-boundary).
  537. ## Acknowledgments
  538. - The pixel whale's 22 hand-drawn frames and its idle behaviors are ported
  539. from **[dsh-ui-whale](https://github.com/lhh010/dsh-ui-whale)**. The frames
  540. were drawn cell by cell in Excel. The idle behaviors are fin flutters, tail
  541. thumps, sleep Z's, and click hearts. dsh-ui-whale is the DeepSeek Harness
  542. web whale-pet plugin by [@lhh010](https://github.com/lhh010), BSD-3-Clause.
  543. Thank you for the art and the inspiration 🐋💜
  544. ## Friends' Links
  545. Community, related projects, and companion tools built by friends:
  546. [see the links page](docs/links.md)
  547. ## Stars
  548. [![Star History](https://raw.githubusercontent.com/ccch1mneyyy/dsh-TUI/bot-star-history/assets/star-history/star-history.png)](https://star-history.com/#ccch1mneyyy/dsh-TUI&Date)
  549. ---
  550. ## Maintainers
  551. <table>
  552. <tbody>
  553. <tr>
  554. <td align="center" width="150"><a href="https://github.com/ccch1mneyyy"><img src="https://github.com/ccch1mneyyy.png?size=160" width="96" height="96" alt="ccch1mneyyy"></a><br><a href="https://github.com/ccch1mneyyy"><b>ccch1mneyyy</b></a><br><sub>Core development &amp; maintenance</sub></td>
  555. <td align="center" width="150"><a href="https://github.com/CikeSeven"><img src="https://github.com/CikeSeven.png?size=160" width="96" height="96" alt="CikeSeven"></a><br><a href="https://github.com/CikeSeven"><b>CikeSeven</b></a><br><sub>Performance &amp; stability</sub></td>
  556. <td align="center" width="150"><a href="https://github.com/T-Auto"><img src="https://github.com/T-Auto.png?size=160" width="96" height="96" alt="T-Auto"></a><br><a href="https://github.com/T-Auto"><b>T-Auto</b></a><br><sub>Architecture &amp; ecosystem adaptation</sub></td>
  557. <td align="center" width="150"><a href="https://github.com/AdamPlatin123"><img src="https://github.com/AdamPlatin123.png?size=160" width="96" height="96" alt="AdamPlatin123"></a><br><a href="https://github.com/AdamPlatin123"><b>AdamPlatin123</b></a><br><sub>Security &amp; interaction</sub></td>
  558. <td align="center" width="150"><a href="https://github.com/Nagi-ovo"><img src="https://github.com/Nagi-ovo.png?size=160" width="96" height="96" alt="Nagi-ovo"></a><br><a href="https://github.com/Nagi-ovo"><b>Nagi-ovo</b></a><br><sub>Test infrastructure &amp; terminal rendering</sub></td>
  559. </tr>
  560. </tbody>
  561. </table>
  562. ※ In no particular order
  563. ---
  564. ## Contributors
  565. [![Contributors](https://contrib.rocks/image?repo=ccch1mneyyy/dsh-TUI)](https://github.com/ccch1mneyyy/dsh-TUI)
  566. ## License
  567. [MIT](LICENSE)
  568. ### Storage migration and read budgets
  569. The SQLite migration script uses the official `node:sqlite.backup()` API on
  570. supported Node 22.19+ and Node 24+ builds. It probes that capability before
  571. opening the source read-only and includes committed WAL data in a consistent
  572. snapshot; it never copies a live database/WAL pair by hand. A build missing the
  573. API reports a migration-specific prerequisite. Session-tree reads validate packed
  574. rows and check their entire member count against the remaining scan budget before
  575. expanding events. Oversized rows report truncation; malformed rows report failure.
  576. The logical budget does not eliminate physical JSON/frame parsing or validation.
  577. Development `@deepseek-ai/*` release-age exceptions list only exact package versions in the current
  578. lockfile (including the legacy SQLite island); all other versions retain the
  579. 24-hour delay. Regenerate with `node scripts/verify-release-age-cohort.mjs --write`
  580. after an intentional lockfile update, then review the cohort diff.
  581. ### Bounded update installation
  582. `/update` and `dsh-tui update` give each installer invocation (profile and engine) a **30-minute
  583. wall-clock limit**. Set `DSH_TUI_UPDATE_TIMEOUT_MS` to a positive integer in
  584. milliseconds to change it (invalid values use the default). Output activity does
  585. not reset this deadline; a quiet but healthy installation can use the full limit.
  586. Only the final process exit code establishes success: a printed `Done` does not.
  587. Ctrl+C cancels the owned installer. On POSIX, cancellation terminates its own
  588. process group, then force-kills remaining descendants after two seconds. Windows
  589. uses a dedicated PowerShell/native supervisor with a private Job Object. The
  590. installer joins that job atomically while suspended; verified membership is required
  591. before it runs. The supervisor retains the job handle after the root exits, so
  592. cancellation and timeout also terminate orphaned descendants holding output pipes.
  593. It does not enable job breakaway or kill processes by name or an exited root PID.
  594. Windows requires Windows 10 / Server 2016 or later and Windows PowerShell with
  595. `Add-Type`/native interop available. Startup or job-membership failures stop the
  596. installation before running an unowned installer. A cleanup failure is reported as
  597. unconfirmed, never as proof that all writes stopped. Timeout, cancellation, or
  598. unconfirmed cleanup returns nonzero and prevents retries, stale-file removal,
  599. repair, and TUI replacement. A partial installation may remain: check/repair that
  600. profile before using the recovery command printed at update start and on failure.
  601. `~/.dsh-tui/restart.log` records installer category, PID, termination reason and last
  602. output timestamp before any restart.
  603. The focused **Windows installer process ownership** workflow runs the real native
  604. regression on `windows-latest`, with Node 24 and no dependency installation. To run
  605. it locally on Windows: `node scripts/verify-update-process-windows.mjs`. It checks
  606. orphan descendants, timeout/cancellation, nested jobs, failure diagnostics, streams,
  607. arguments and an unrelated process; a Linux run explicitly skips native acceptance.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.