dsh-TUI: a Claude Code style terminal front end for DeepSeek Harness

What dsh-TUI adds to a DeepSeek Harness session

DeepSeek Harness is the agent runtime; dsh-TUI is the terminal face on top of it. The README describes the package as an interactive terminal interface plugin for DeepSeek Harness, and the split matters: the TUI is mounted as a plugin rather than forked into the runtime. The README states that enabling it requires installing the plugin and that uninstalling leaves no core patches behind. That claim is the whole reason to care about the packaging. If you have ever maintained a patched copy of an agent CLI across upstream releases, you know the alternative.

The audience is narrow and specific. You need Node.js, deepseek-harness installed, and a registered DEEPSEEK_API_KEY before any of this runs. Within that group, the plugin targets people who live in a terminal all day and want the affordances a coding agent UI usually has: a status line that shows what the agent is doing, a visible reasoning stream, a way to rewind a turn, and a sense of how full the context window is. The homepage is dshtui.com and the package is published on npm as @deepseek-harness-tui/dsh-tui.

The README also notes a VS Code route. It links a docs page for starting dsh-TUI as a VS Code extension and says the extension is listed on the VS Code Marketplace. So the same interface has two hosts, terminal and editor, which is worth knowing before you decide the terminal is the only place it lives.

Plugin mounting, profile layering and what the seams cost

The install path reveals the architecture. Rather than editing configuration by hand, dsh-TUI is added to a DeepSeek Harness profile, and the README treats dsh-tui and dsh --profile dsh-tui as equivalent commands. That means the plugin is a profile composition, not a global override. The repository root carries cordis.yml and a cordis.patch.yml, and the topics list includes cordis, so the plugin mechanism runs through the Cordis composition layer that DeepSeek Harness uses.

The README is unusually candid about which extension points are safe. It publishes an informal tiering: settings blocks, fullscreen scenarios, hosted dialogs, the status line, keyboard shortcuts and item renderers are listed as stable candidates, meaning the shape is frozen and a breaking change would first ship a deprecation warning in a minor release. Decision events and toast notifications (ctx.tuiToast) are marked experimental. Session events, official prompt slots, skill packaging, themes, system prompt sections and profile composition are marked as following upstream, so their stability is decided by Cordis and DeepSeek Harness, not by this project.

That table is the most useful thing in the README for anyone building on top. It is also a warning. The page calls the tiering informal and defers the formal contract to an external plugin admission and development guide in a separate repository, T-Auto/dsh-ecosystem-spec. If you write a plugin against the experimental seams, you are accepting churn that the project has already told you to expect. The pure type entry point, @deepseek-harness-tui/dsh-tui/api, is described as an experimental public surface as well.

Installing dsh-TUI and a first session

The README lists three prerequisites before the install command: Node.js, deepseek-harness, and a registered DEEPSEEK_API_KEY. The global install pulls both the harness and the plugin in one line.

npm install -g @deepseek-ai/dsh @deepseek-harness-tui/dsh-tui

After that, the launcher is a single command. The README gives a short alias for people who do not want to type the full name.

dsh-tui
# or, if you do not want to press keys seven times
dst

If you prefer to install the plugin manually, the repository root ships install.sh. The README shows both the script and the equivalent explicit plugin command, and notes that after either one, dsh-tui and dsh --profile dsh-tui behave the same.

sh install.sh
# or: dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui

The README flags one install-time snag for new users. With pnpm 11 or later, builds that carry install scripts are blocked by default, and the plugin install can fail with ERR_PNPM_IGNORED_BUILDS for dependencies such as @google/genai and protobufjs. The README says those scripts are not needed at runtime and can be ignored, and gives the allowBuilds block to add to the profile's pnpm-workspace.yaml. It also states that /update and dsh-tui update write this configuration automatically, so the manual step is only for the first install.

allowBuilds:
  '@google/genai': false
  protobufjs: false

Once the session is up, the commands worth knowing are the ones the README documents: /resume for browsing history by working directory, /agentview for a session overview, /new, /compact, /export, /btw, /skills, /settings and /restart. Configuration changes made in /settings take effect after /restart, and saved /settings choices take precedence over the Cordis configuration file.

Terminal images are the feature with the most caveats

Version 0.10.0 introduced in-terminal images, and 0.10.1 followed with the context progress bar on by default and collapsing for very long single lines. The image path is where the plugin's constraints become visible. The README says protocol detection prefers Kitty graphics and otherwise uses the Sixel capability declared through DA1, and that DSH_TUI_IMAGE_PROTOCOL=auto|kitty|sixel|none overrides the choice.

Several environments still fall back to text. The README lists accessibility mode, non-TTY output and tmux or screen as places where graphics stay disabled, and DSH_TUI_DISABLE_TERMINAL_IMAGES=1 forces previews off. Missing image dependencies or an encoding failure also fall back to text, and forcing a protocol does not enable inline Sixel. That last detail is the honest one: the environment variable selects among available protocols, it does not conjure capability the terminal lacks.

The rendering design is documented in more depth than most terminal projects bother with. Sixel uses an adaptive palette of at most 256 colors, composites transparent pixels against the background, and a worker caches quantization results so scrolling only encodes the visible portion, erasing old images when they leave the viewport or are covered by an overlay. Attachment reads and decodes run at most two at a time, and a read is cancelled when the last consumer leaves. Multi-image caches, queued work and single-frame transfers all have capacity limits, and exceeding them keeps the text fallback. Large previews budget roughly 95 percent of the conversation area's width and height, with a longest edge up to 2048 pixels, and 100 percent zoom requires the terminal to report character cell pixel dimensions. None of this is free, and the README is clear that the caps exist to bound background cost.

Where dsh-TUI is the wrong choice

The package badge says public beta, and the repository's own seam table marks decision events and toast notifications as experimental. If you are building automation on top of the TUI, or you need an extension surface that will not move under you, this is not the moment to commit. The README points you at an external admission and development guide for the formal contract, which is a sign the contract is still being written.

The image feature has a hard environmental floor. On tmux or screen, in non-TTY output, or in accessibility mode, previews are disabled by design. If your workflow runs inside a multiplexer, the visual part of the plugin degrades to the text fallback, and the effort spent on Sixel compositing buys you nothing.

There is also a configuration precedence rule that can confuse people. The README states that a saved /settings choice wins over the Cordis configuration, so if you once saved terminal image previews as enabled, setting terminalImages: false in the config file will not turn them off. You have to disable it in /settings and then run /restart. Anyone who edits only the YAML and expects the change to apply will conclude the setting is broken. It is not broken; it is overridden.

Finally, the plugin assumes DeepSeek Harness as the runtime. Everything here, the profile composition, the session events, the skill discovery through /skills, is scoped to that harness. If you use a different agent CLI, dsh-TUI is not a drop-in front end.

dsh-TUI versus a standalone terminal agent UI

The obvious comparison is a standalone terminal coding agent that ships its own interface and its own runtime in one package. That approach gives you a single install and no profile concept to learn. The trade-off is that the interface and the agent are versioned together, so a UI change and a runtime change arrive in the same release, and you cannot swap one without the other.

dsh-TUI inverts that. The runtime is DeepSeek Harness, installed separately as @deepseek-ai/dsh, and the interface is a plugin mounted into a named profile. The README's claim that uninstalling leaves no core patches is the payoff: you can remove the TUI and keep the harness, or run the harness headless, without unpicking edits. The cost is a second moving part. You now track two version streams, and the plugin's compatibility depends on seams owned by Cordis and DeepSeek Harness, which the README itself lists as following upstream.

For teams already standardized on DeepSeek Harness, the plugin model is the better fit, because the interface becomes a choice rather than a constraint. For someone who has not chosen a harness yet, adding a plugin layer before picking the runtime is work you may not need. The deciding question is not which interface looks better; it is whether you want the interface and the runtime to be independently replaceable.

Licence, upgrade path and the cost of staying current

The package is MIT licensed, and the repository root carries a LICENSE file plus a THIRD_PARTY_LICENSES file. That second file matters more than usual here, because the README credits the whale artwork directly: the 22 hand-drawn frames and the idle behavior are ported from dsh-ui-whale by @lhh010. MIT covers the code; the provenance of bundled art and any third-party components is what THIRD_PARTY_LICENSES is for, and it is the file to read before you redistribute the package inside a product. This is a description of what the repository contains, not legal advice.

Upgrades are handled in-band. The README mentions /update and dsh-tui update, and states that they write the pnpm allowBuilds configuration automatically, which removes the first-install manual step on subsequent upgrades. The plugin also advertises automatic updates. That is convenient, and it also means the version you run can move without a deliberate install. If you need reproducible environments, pin the package version in your profile rather than relying on the update path.

The maintenance signal is current: the last push to the repository was on 2026-09-16, and the most recent release listed is v0.10.1 on 2026-09-10. Release cadence through the 0.10 line has been brisk, with a beta series in early September followed by the stable 0.10.0 and then 0.10.1. Brisk cadence on a public beta is a double-edged signal: fixes arrive quickly, and so do interface changes. Budget for reading the changelog rather than assuming the previous release notes still describe the current behavior.

Editorial conclusion

Adopt dsh-TUI if you already run DeepSeek Harness interactively and want session history browsing, an activity line and terminal image previews without touching core files; the README states that uninstalling leaves no core patches, which is the property to check on your own profile. Skip it if you need a stable plugin API today: the repository labels its own seam list as informal, with settings blocks and keyboard shortcuts as stable candidates and decision events plus toast notifications as experimental, and the package badge says public beta. Verify first that Node and deepseek-harness are installed and that DEEPSEEK_API_KEY is registered, then run the plugin install and confirm the profile loads before you rely on /resume or /settings.

Frequently asked questions

Official sources

1. ccch1mneyyy/dsh-TUI on GitHub
2. License: MIT
3. Project website
4. README
5. Releases