Skip to main content

deepseek-harness-tui

45Stars4Forks1Issues0Watchers

A terminal-native interaction interface for DeepSeek Harness. Connects to agents via ACP protocol and supports client plugin extensions including themes, commands, and slots.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
Rust
License
MIT
Branch
main
agentagentsdeepseek-harnessdeepseek-harness-plugindeepseek-harness-plugin-devdeepseek-harness-pluginsdsh-plugindsh-plugins

Install

cmdweb profile
$ dsh plugin --profile web add github:openma-ai/deepseek-harness-tui

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin openma-ai/deepseek-harness-tui for me: review the repository at https://github.com/openma-ai/deepseek-harness-tui first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-line Description

A terminal-native interactive interface ("client" in the terminal) for DeepSeek Harness (DSH), communicating with agents via the ACP protocol to render streaming reasoning, tool calls, Skills, multi-image prompts, and persistent sessions in the terminal. It serves as a terminal surface plugin for the DSH ecosystem, recommended to install into the tui profile and launch with dsh --profile tui.

Core Features

  • Real-time agent timeline display: streaming reasoning, responses, tool parameters and results, subagent lifecycle, and per-turn token and cache usage
  • Reads agent-declared models, permissions, authentication methods, and available commands via ACP, merging them with built-in commands into a searchable, scrollable / slash menu
  • Multi-image prompt: load up to 8 images from files, clipboard, or paste buffer, displayed as editable [image n] chips inline in the draft when sending
  • Terminal-friendly Markdown rendering: headings, lists, quotes, code blocks, inline code, emphasis, strikethrough, links, images, with CJK/Latin mixed text preserved
  • High-density tool view: long results default to showing only the last 4 lines with click-to-expand, status (in-progress/success/failed) clearly visible
  • Long session control: follow-ups can be queued mid-turn, or immediately steer the current turn; persistent JSONL sessions managed via /new, /resume, and --session-id
  • Cross-platform input: readline editing, context shortcuts, macOS physical ⌘/⌥, Linux/Windows ctrl key combos for unified feel
  • Terminal-native UI: light/dark themes, narrow-width adaptation, mouse selection, native/tmux/OSC 52 clipboard, image preview via kitty graphics protocol, and optional /liang pixel pet

Technical Implementation

  • Language: TypeScript / Node.js (Cordis client tree on npm) + Rust / ratatui (terminal rendering and state machine)
  • Key Dependencies: @deepseek-ai/cordis (Cordis plugin container), @openma/deepseek-harness-acp (ACP client carried at runtime, serving as agent endpoint), agent-client-protocol Rust crate (communicates with agent), ratatui + tui-markdown (terminal rendering)
  • Architecture Pattern: Dual-process Cordis architecture. The Host process mounts the ACP plugin in its own Base Cordis tree, which then spawns an independent TUI Client child process; the two trees communicate solely via ACP protocol over the child process's stdin/stdout. On Unix, fd 3/4 of the Client process carries only the user TTY; on Windows, it uses loopback TCP with a random token. The plugin extends via Cordis services (tuiTheme, tuiSlots, tuiCommands, tuiOverlay, acpSessionConfig/Plan/Stats); theme and view capabilities negotiate via _dsh/cordis/* and _dsh/cordis/tui/* extension points
  • Entry Points: npm/bin/dsh-tui.js (CLI shim), npm/lib/index.js (dsh-tui-shell Cordis plugin, responsible for spawning Rust painter and muxing ACP + compositor), src/main.rs (Rust entry)

Use Cases

Users who want to use DeepSeek Harness in the terminal instead of a browser, especially those relying on tmux/ssh, needing quick keyboard/mouse operations, wanting scriptable invocation, or who dislike opening browser windows. It's also great for demos: running --demo alone lets you browse the UI experience without API key configuration; adding --demo-skin lets you switch to the built-in ember color scheme to see theme switching in action.

Prerequisites & Compatibility

DependencyMin VersionDescription
Node.js>= 18Cordis client tree on npm and CLI shim require Node 18+
DeepSeek Harness0.1.0-rc.6+Installation command handles automatically; this plugin declares @deepseek-ai/[email protected] in devDependencies
ACP Client (dsh-acp)0.4.13+Carried as runtime dependency, automatically mounted on profile main path; in standalone mode, can specify other ACP server
Operating SystemmacOS arm64/x64, Linux arm64/x64, Windows x64Linux x64 changed to static musl linking from 0.2.x, no host glibc version dependency
Native ModulesNoneRust binaries precompiled and published with the package to npm/vendor/<platform>-<arch>/, no node-gyp involved

Installation

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

Configuration

This plugin requires no additional configuration. Behaviors for /auth, /model, /agent, /effort, /plan, /permission, /theme, /keys, /help, /image, /clip, /liang, /new, /resume, !cmd, etc. are driven directly by the agent's own capabilities, runtime state, or runtime commands.

The following environment variables are for development and troubleshooting only; regular users don't need to care:

Environment VariablePurpose
DSH_TUI_BINOverride Rust painter path, used when debugging locally with cargo build output
DSH_TUI_AGENTOverride the default ACP agent command that standalone entry searches for
DSH_TUI_FORCE_TCP=1Force loopback TCP with token on Unix (default is TCP only on Windows)
DSH_HOMEOverride DSH profile and home directory search path

FAQ

Q: Do I need additional configuration after installation?

A: No. The installation command automatically creates the profile and installs the TUI and ACP dependencies together. You can start using it directly with dsh --profile tui. The DSH_TUI_BIN environment variable is only needed when debugging locally compiled Rust output.

Q: Can I run without DSH Harness installed?

A: Yes. The standalone entry dsh-tui can connect to any ACP-capable agent via --agent dsh-acp or --agent dsh --agent-arg --profile --agent-arg acp. The --demo mode lets you preview the UI without any agent or API key.

Q: Which operating systems are supported?

A: macOS (arm64 / x64), Linux (arm64 / x64), Windows (x64). Linux x64 packages changed to static musl linking from 0.2.x, allowing direct execution on older distros (e.g., Ubuntu 20.04) without glibc compatibility layer.

Q: Can I use ACP agents that don't support DSH private extensions?

A: Yes. When the agent doesn't declare the extension in _meta.dsh.cordis during initialize, the TUI only uses standard ACP (prompt, session, auth, update), and there are no compatibility issues.

Q: The Liang pixel pet next to the input box doesn't display. What should I do?

A: Only terminals supporting the kitty graphics protocol (Ghostty, Kitty, WezTerm, etc.) display the RGBA pixel sprite; other terminals fall back to a half-block character whale, and it's automatically hidden when width is below 60 columns. Main interface functionality is unaffected.

Q: How do I uninstall?

A: Run dsh plugin --profile tui remove @openma/deepseek-harness-tui, which will also remove the TUI bundle and associated ACP/Host rows from the profile.

Q: Getting spawn dsh-acp ENOENT error. What now?

A: The default agent binary wasn't found. You can install the official DSH ACP client (dsh-acp), or explicitly point to another ACP server via --agent, e.g., --agent <other ACP command>.

Q: Package prompts no native binary for ... What should I do?

A: Your platform isn't covered by the current installation version (outside of darwin-arm64/x64, linux-arm64/x64, win32-x64). Make sure you're on the latest version, or run scripts/build-npm.sh locally to build the package yourself.

Learning Curve

Beginner — one installation command gets you started. Advanced users can read docs/plugins.md to write client plugins extending themes, slots, commands, etc.

Known Issues & Limitations

  • Conversation timeline slot (conversation.chat) is not yet open; currently the plugin can only contribute chrome.right, conversation.input.dock, conversation.composer.dock. ACP session/update remains the sole source of truth for transcript; plugin nodes cannot replace the composer or masquerade as session events
  • "Fully pluginized" is still the target architecture; form controls, more shell/conversation slots, runtime diagnostics panel, and independent ViewPreset are still on the migration roadmap. See docs/migration.md for details
  • Third-party plugins are strictly limited to semantic APIs like tuiTheme/tuiSlots/tuiCommands/tuiOverlay/ACP session services; TTY, raw mode, ratatui, kitty escapes, absolute row/column coordinates, and JSON-RPC method tables are not exposed to plugins. Any code that directly reads stdin or ratatui state at runtime will break in new versions
  • The /liang pixel pet next to the input box only displays as RGBA pixels on terminals supporting the kitty graphics protocol; other terminals fall back to a half-block character whale; it's directly hidden when terminal width is below 60 columns (README.md:312-314)
  • If the package prompts no native binary for ..., it's because that platform isn't in the packaging matrix (darwin-arm64/x64, linux-arm64/x64, win32-x64). You need to self-compile via scripts/build-npm.sh locally, or switch to a package matching your platform

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/openma-ai/deepseek-harness-tui)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory