Preface¶
DeepSeek Harness (CLI tool: dsh) is an open-source agent runtime from DeepSeek, whose core philosophy is “everything is a plugin”: model adapters, tools, sessions, sandboxes, and even the UI itself can be replaced via plugins. The official onboarding path is straightforward: after installing Node.js, run npx @deepseek-ai/dsh web, and a Web UI will start by default.
This workflow works well for clicking and viewing tasks in a browser. But if you spend most of your time in SSH, tmux, or a pure terminal environment, opening a browser may not be the most convenient option. The community has therefore built several terminal UI (TUI) plugins. This article introduces one of the more minimalist ones: deepseek-harness-tui. It does not rewrite the harness, but uses Ink—a terminal renderer for React—to render existing sessions in the terminal.
First, a note on the source: the plugin is maintained by gxinxing, licensed under MIT, and categorized as “UI Enhancement”. At the time of writing, both the community plugin directory page and the GitHub repo have 7 stars. The directory site is an independent community index with no official affiliation to DeepSeek / Horizon Robotics; the repo’s README also clarifies that this is an independent community project with no association to DeepSeek or TokenDance.
What It Is¶
One-sentence positioning: deepseek-harness-tui is a terminal chat interface plugin that plugs into dsh. With a TokenDance API Key and a working dsh installation, run dsh --profile tui to get a terminal chat interface with almost no border decorations.
The repo’s README describes it as “a minimalist plugin with ~800 lines of UI, not a reimplementation of the harness”. This is confirmed by package.json: it declares a dsh.bundle.patch, and depends on packages like @deepseek-ai/dsh-agent, @deepseek-ai/dsh-session, ink, and react. The version badge targets dsh 0.1.0-rc.6. This means model calls, tool execution, and session persistence are still handled by Harness’s own services, and this plugin primarily projects session/event data into terminal UI.
The package.json has "private": true, so it is not currently distributed as a public npm package. The installation entry on the directory page uses a GitHub source instead of an npm install for a scoped package.
Core Features¶
The following capabilities are consistent across the plugin directory page and the repo’s README:
1. Conversation flow as the UI. No extra boxes or decorative layers. An empty session will show the DeepSeek brand banner (ANSI Shadow logo, gradient color scheme); once a conversation starts, the main area is the transcript. The current model and working directory are placed in a darker footer at the bottom.
2. Tool calls grouped into cells. A running tool will display ⠋ Running, and after completion it will change to ✓ • 1.2s (failed calls will show ✗). Tool outputs are merged into the same cell, dimmed, and truncated with … +N lines to avoid flooding the terminal with raw logs.
3. Theme follows your terminal. It detects the real background color via OSC 11, and adjusts the message background and inline code chips based on the background: dark terminals use 12% white overlay, light terminals use 4% black overlay, with no hardcoded hex color values. You can force the background with an environment variable during debugging:
DSH_TUI_BG=#ffffff
4. Foldable thinking track. Press ctrl + t to toggle expanding or collapsing the reasoning trail. Press esc at any time to abort the current turn via agent.cancel({ kind: 'user' }).
5. Markdown rendered as close to original as possible. Headings retain their # prefix, fenced code blocks keep their delimiters, and inline code has chip-style backgrounds. Chinese, English, and emoji are wrapped by character width, with gutter alignment.
6. Viewport pinned to the bottom. The latest content is always visible. When busy, it shows a braille spinner and compact timer, for example Working 5s.
The repo also includes INTEGRATION-NOTES.md, which documents how session/event maps to the UI, the semantics of patches, and how it connects with dsh profiles and bundles. This is intended for developers modifying the event bridge, and does not need to be read before daily use.
Installation and Activation¶
Runtime requirements: Node.js ≥ 20, and an installed DeepSeek Harness CLI. The installation command given on the plugin directory page can be run directly in the DeepSeek Harness terminal:
dsh plugin add github:gxinxing/deepseek-harness-tui
For a reproducible installation, pin the commit hash as instructed on the directory page:
dsh plugin add github:gxinxing/deepseek-harness-tui#<commit>
Replace <commit> with the actual commit hash from the repository. Do not guess randomly.
The repo’s README also includes a local development setup path: first install dsh globally, then clone the source code and install dependencies with pnpm, then attach the plugin to a profile named tui.
npm install -g @deepseek-ai/dsh # harness (README notes no Homebrew tap is available yet)
git clone https://github.com/gxinxing/deepseek-harness-tui
cd deepseek-harness-tui && pnpm install
Write to the tui profile in one go:
dsh plugin --profile tui add @deepseek-ai/dsh-headless
dsh plugin --profile tui add /path/to/deepseek-harness-tui
Replace the second path with the local directory you cloned the repo to. This setup links the package as a local link: dependency in the profile, which is suitable for modifying the UI source code; for trial use only, prefer the github:gxinxing/deepseek-harness-tui command from the directory page.
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.
Typical Usage¶
Per the README, you need a TokenDance API Key before starting. You can export it as an environment variable, or write it to ~/.dsh/.credentials.yaml (permissions 0600):
export TOKENDANCE_API_KEY=sk-...
dsh --profile tui
Once in the TUI:
- ctrl + t: Toggle folding or expanding the thinking track
- esc: Abort the current turn
- /help: View all key bindings and commands
The model routing is also documented in the repo. The profile patch cordis.patch.yml points llm-deepseek to the TokenDance gateway:
llm-deepseek:
apiKeyEnv: TOKENDANCE_API_KEY
baseURL: https://tokendance.space/gateway/v1
The README states that the provider is registered under llm-pi-ai.providers.tokendance in ~/.dsh/settings.yaml: an OpenAI-compatible endpoint with thinkingFormat: deepseek, and models deepseek-v4-flash (default) and deepseek-v4-pro. You can change the model list, or override llm-deepseek.model in the profile patch.
There is a documented limitation here. When TokenDance streams subsequent tool-call deltas, the name / id fields may be empty strings. If the official @deepseek-ai/dsh-llm-deepseek adapter uses empty strings to overwrite the call ID in the first frame, Harness will get stuck in an unknown tool "" loop. The README provides a one-time fix by editing the guard clause in the globally installed node_modules/@deepseek-ai/dsh-llm-deepseek/lib/index.js (change !== void 0 to also reject empty strings), and notes that this change will be lost after upgrading dsh and will need to be reapplied. This is not a bug in the plugin itself, but a known issue with the current gateway and official adapter combination. Before editing node_modules, refer to the original README text, and follow upstream updates to see if a fix has been merged.
Use Cases and Notes¶
It is well-suited for the following scenarios:
- You already use dsh and want to chat directly in your SSH/local terminal instead of opening a Web UI.
- You want to see a minimal TUI example: the UI uses Ink + React, while agent logic is still handled by Harness.
- You can use the TokenDance model routing and have a corresponding API Key.
There are also cases where it is less suitable:
- It does not work out of the box with DEEPSEEK_API_KEY for the official DeepSeek API. The current profile points llm-deepseek to TokenDance. If your environment does not use this gateway, you will need to modify the patch yourself, and cannot assume it will connect to the official DeepSeek API by default.
- There are more fully featured terminal plugins in the community directory, such as dsh-TUI (Claude Code style, npm-installable) also under the “UI Enhancement” category. deepseek-harness-tui prioritizes minimalism and readability over a long feature list. Your choice depends on whether you want a thin UI wrapper or a full TUI with session workflows.
- The engines field in package.json requires Node.js ≥ 20; the README badge targets dsh 0.1.0-rc.6. Harness is still in developer preview, and plugin APIs may change going forward.
- The plugin runs with the permissions of the current dsh process. Before installing community plugins, you should read the source code and MIT license to confirm you accept this permission model.
Summary¶
deepseek-harness-tui has a focused purpose: add a borderless terminal chat interface to dsh without rewriting the harness. Features like grouping tool calls into cells, foldable thinking tracks, and terminal-following theme are documented consistently on both the directory page and README.
It is a community plugin maintained by gxinxing, licensed under MIT, and not an official first-party offering from the app store. Use the installation command from the directory page:
dsh plugin add github:gxinxing/deepseek-harness-tui
Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/deepseek-harness-tui-gxinxing/
GitHub: https://github.com/gxinxing/deepseek-harness-tui
Official DeepSeek Harness repo: https://github.com/deepseek-ai/deepseek-harness