Preface¶

The default entry point for DeepSeek Harness (hereafter referred to as dsh) is the local Web UI. The quick start command provided on the official developer preview page is npx @deepseek-ai/dsh web, with capabilities such as interface, tools, sessions, and permissions all mounted onto the Cordis kernel under the “everything is a plugin” paradigm. For users accustomed to working via SSH, tmux, or a pure terminal, launching a browser is not the most convenient workflow. The UI itself is also a plugin, so switching to a terminal interface does not require modifying dsh’s source code.

deepseek-harness-tui is built along this path: it uses Rust and ratatui to render an agent timeline in the terminal, integrating streaming inference, tool calls, Skills, multi-image prompts, and persistent sessions into a single interface. It is maintained by openma-ai, licensed under MIT, and the current npm/Cargo version is 0.2.1. The community plugin directory lists it under “Interface Enhancements”, with an inclusion date of 2026-08-15. This article was written on 2026-08-17, and the GitHub repository has 34 stars.

Two key points need clarification first. First, the community plugin directory (deepseek-harness-plugin.com) is an independent site with no official affiliation to DeepSeek / Fangxin, and should not be treated as an official app store. Second, there are TUI projects in the directory with very similar names, such as the featured plugin dsh-TUI. This article only covers the version maintained by openma-ai with the npm package name @openma/deepseek-harness-tui — please verify the repository and package name when installing.

The repository README also clearly states: this project has no affiliation with DeepSeek or xAI; the interaction design references grok-build, and the runtime backend is DeepSeek Harness.

What is this¶

One-sentence positioning: deepseek-harness-tui (command name dsh-tui) is the terminal-native agent UI for DeepSeek Harness.

It solves a very specific problem. The default Web UI works well for local browsers; but when you are on a server, jump host, or simply do not want to leave the terminal, there is no TTY-based interface to view inference progress, tool results, token usage, and session recovery. This plugin renders all the above information into a ratatui interface, and offers two connection methods:

1. Run as a dsh profile plugin (recommended by the repository). Agents, tools, providers, credentials, and callable skills all come from the host profile, and the TUI only handles presentation and input.
2. Standalone mode, directly connected to the SDK JSON-RPC runtime. The interface remains the same, and the session directory is changed to ~/.dsh-tui/sessions.

The plugin runner launches a platform-native binary on the host TTY, providing a JSON-RPC compatible with the official SDK server via Unix fd 3/4, or authenticated loopback TCP on Windows. It does not directly mount @deepseek-ai/dsh-sdk-jsonrpc-server into the profile; agents, tools, providers, and persistence are still provided by the surrounding dsh profile. The plugin ID in the Cordis patch is the stable tui-runner.

Core Capabilities¶

The capabilities listed in the repository README can be understood in the order of use:

1. Complete agent timeline. Inference, replies, tool parameters and results, plugin context, sub-agent lifecycle, token/cache metrics will all be drawn on a single timeline in real time. The latest message will continuously display the current phase, elapsed time, and queue depth below it.
2. Native host capability integration. In plugin mode, it reads dsh’s models, agent presets, permissions, providers, credentials, and callable skills. Skills share a searchable, scrollable slash menu with built-in commands. Starting from version 0.2.0, the slash menu will go through the runner’s tui/skills to filter user-callable skills; after selection, it will fall into /name and be sent as a regular prompt, with the skill body injected by the host.
3. Multi-image prompts. Up to 8 images can be temporarily stored from files, clipboard, or paste operations, displayed inline as editable [image n] chips in the draft, with previews of name, dimensions, size, and type supported. The sending order matches the token order.
4. Terminal-friendly Markdown. Headers, lists, blockquotes, code blocks, inline code, emphasis, strikethrough, links, and image markers can all be rendered, while retaining mixed CJK/Latin typesetting and soft line breaks.
5. High-density tool view. Tool calls are distinguished by in-progress, success, and failure states; results can be collapsed, and long outputs have independent scrollable windows without pushing the entire conversation off-screen.
6. Controls for long conversations. You can queue follow-ups during a turn, or interrupt and send immediately. Persistent JSONL sessions are managed with /new, /resume, and --session-id. In plugin mode, sessions are written to ~/.dsh/sessions.
7. Cross-platform input. Readline editing, context-aware shortcuts; on macOS, it will directly read physical ⌘/⌥ states, while Linux/Windows use ctrl combinations to make line start/end, word jump, and word deletion consistent across different terminals as much as possible.
8. Terminal-native interface. Light/dark themes, narrow-screen layout, mouse selection and tool interaction, native/tmux/OSC 52 clipboard. Terminals supporting the kitty graphics protocol can preview images, and the optional /liang pixel pet is also available. Ghostty, Kitty, WezTerm, etc., will display RGBA sprites, while other terminals fall back to half-block character whales; they will automatically hide when the width is less than 60 columns.

The current integration baseline is listed in the README: dsh 0.1.0-rc.6, Node.js 18+, pnpm 10+. The official npm package includes four native binaries: macOS Apple Silicon (darwin-arm64), macOS Intel (darwin-x64), Linux x64, and Windows x64.

Installation and Activation¶

The installation command given on the community directory page is as follows, run it in an already installed DeepSeek Harness terminal:

dsh plugin add github:openma-ai/deepseek-harness-tui

The directory page also reminds users that for reproducible installations, please pin the commit hash:

dsh plugin add github:openma-ai/deepseek-harness-tui#commit

Replace #commit with the actual commit hash. The plugin runs with the permissions of the current dsh process, and may execute code during installation. You should inspect the source repository and license before installing.

The repository README more strongly recommends installing the npm package via profile, rather than just adding the GitHub source. The prerequisites are an already installed and configured dsh, Node.js 18+, and pnpm 10+. The installation command does not require -w:

dsh plugin --profile tui add @openma/deepseek-harness-tui
dsh --profile tui

After installation, you can use the following command to confirm that the bundle has been mounted as tui-runner:

dsh --profile tui --dump-config

If you just want to try the interface first, without connecting to a runtime or preparing an API key, you can use the demo:

npm install --global @openma/deepseek-harness-tui
dsh-tui --demo

The main command is dsh-tui, and dsb is a compatible alias. To uninstall the global package:

npm uninstall --global @openma/deepseek-harness-tui

Standalone mode requires more than just installing the TUI binary: you also need to install the DeepSeek Harness SDK in a .venv near the workspace, or explicitly specify the runtime:

python -m venv .venv
.venv/bin/pip install deepseek-harness-sdk
dsh-tui --workspace .

You can also set DSH_RUNTIME_BIN, or pass --runtime-bin. Credentials preferentially use --api-key, DEEPSEEK_API_KEY, and then attempt to read the local ~/.dsh configuration. When dsh-jsonrpc-agent cannot be found, the README recommends installing the SDK, setting environment variables, or switching back to plugin mode.

Common Operations¶

After entering the interface, the key bindings and commands given by the repository are as follows. The full list can be viewed in the interface with /help and /keys.

A few mode-related differences are worth noting separately:
- In plugin mode, ctrl+x forwards the interrupt to the host without performing a hard interrupt; in Standalone mode, esc will stop the runtime, but the session log will still be retained.
- /model, /permission, /image, and the full skill catalog depend on plugin mode.
- The /liang button on the right side of the input box can be explicitly toggled on and off with /liang on and /liang off, without affecting the main interface functions.

The session directories for the two modes also differ: plugin mode writes to ~/.dsh/sessions, while Standalone mode defaults to ~/.dsh-tui/sessions, which can be modified with --session-root.

Applicable Scenarios and Notes¶

It is suitable for the following use cases: already using dsh but preferring to view inference and tool processes in the terminal; needing SSH/tmux remote sessions where browsers are inconvenient; wanting to reuse the host’s models, permissions, skills, and sessions instead of setting up a separate web interface.

There are several things to check before installing and running:

1. Permission Model. The plugin runs with the permissions of the current dsh process, and may execute code during installation. Read the repository source code and MIT license before installing, and do not paste unknown GitHub addresses directly into production environment profiles.
2. Platform Restrictions. The npm package currently only includes four sets of binaries: darwin-arm64, darwin-x64, linux-x64, and win32-x64. If you get the error no native binary for ... on startup, first confirm that you have installed the latest version and that your platform is in this matrix. The repository provides a source build path: you need Rust stable and Node.js 18+, and the local script will only build for the current platform.
3. Version Baseline. The README states that the current integration baseline is dsh 0.1.0-rc.6. dsh is still in developer preview, and core plugins and APIs will continue to change, so pinning the version is more reliable than tracking latest. Runners 0.1.0 and earlier are CJS, which may race with ESM plugins loaded in parallel with dsh for the same module, resulting in ERR_REQUIRE_ESM_RACE_CONDITION; the repository requires upgrading to 0.1.1 or higher. The published package verified in this article is 0.2.1.
4. pnpm. If you encounter workspace root-related errors, the README’s solution is to upgrade to pnpm 10+, then re-run the installation command without -w.
5. Pixel Pet and Image Preview. Depends on the kitty graphics protocol. The main interface will still be available if the terminal does not support it, only the pet or thumbnails will fall back to degraded display.
6. Duplicate-named Plugins. There are at least other TUI implementations in the community directory, with different package names, maintainers, and installation commands. Confirm that you are using github:openma-ai/deepseek-harness-tui or @openma/deepseek-harness-tui to avoid installing another interface.

Summary¶

deepseek-harness-tui does something very restrained: it does not replace dsh’s agent loop, it only turns the terminal into an interface that can view streaming inference, tool calls, skills, and persistent sessions. The recommended path is dsh plugin --profile tui add @openma/deepseek-harness-tui, then start with dsh --profile tui; the equivalent entry on the directory page is dsh plugin add github:openma-ai/deepseek-harness-tui. To try the interface first without connecting to a runtime or needing an API key, use dsh-tui --demo.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/deepseek-harness-tui/

GitHub: https://github.com/openma-ai/deepseek-harness-tui

npm: https://www.npmjs.com/package/@openma/deepseek-harness-tui