Preface¶

DeepSeek Harness (hereinafter referred to as dsh) is an Agent runtime open-sourced by DeepSeek, whose core philosophy is “everything is a plugin”: models, tools, sessions, sandboxes, scheduling, and even the interface can be replaced at the configuration layer without modifying the Harness source code. The official entry point is the Web UI, which can be started with a single command npx @deepseek-ai/dsh web.

People who write code in terminals often prefer full-screen TUIs: scrollback, keyboard shortcuts, permission prompts, and sessions in the current working directory. The grok-build from xAI / SpaceXAI is exactly such an interface. The problem is: you want to use grok’s terminal interaction style without switching your prompt templates, tools, and session storage to another kernel.

The community plugin dsh-grok-tui does exactly this. It connects grok-build’s TUI to dsh: the interface is grok’s, but the kernel remains dsh. This article is written after cross-verifying information from the plugin directory page, GitHub README, and repository documentation. The DeepSeek Harness Plugin Repository mentioned in the text is an independent community site and has no official affiliation with DeepSeek / Magic Square. Do not treat it as an official app store.

What It Is¶

dsh-grok-tui is an interface enhancement plugin maintained by chen-001, with the repository address at chen-001/dsh-grok-tui. The directory page describes its positioning concisely: use dsh via grok-build’s TUI.

The repository README clarifies the boundaries more clearly: it only borrows grok’s frontend; prompt templates, tools, model routing, and session persistence are still provided by dsh. The architecture documentation adds one more detail: grok-shell’s built-in Agent runtime will not actually start—the pager binary in leader mode connects to the service provided by this plugin instead of spinning up its own Agent set.

As of the verification date of this article (2026-08-17):
- License: MIT
- Primary language: TypeScript
- npm package version: 0.3.8 (subject to the repository’s package.json)
- GitHub stars: 10
- Runtime environment: macOS / Linux; Node.js requirement: ^22.19.0 || >=24.0.0
- Platform limitation: Leader communication uses Unix socket; Windows named pipe is not yet implemented

It solves a specific pain point: users already using dsh do not need to set up another Harness just for terminal interaction; users already familiar with grok TUI can keep their sessions, tools, and model routing within dsh.

Core Features¶

Based on the directory page, README, and docs/ARCHITECTURE.md, the verified capabilities as of now are as follows.

1. Frontend and kernel separation. The plugin implements grok’s leader protocol over Unix socket, then maps Agent Client Protocol (ACP) methods to dsh’s ctx.agents / ctx.llm and other services. System prompt assembly, tool registration, approval, sandboxing, and session persistence all remain on the dsh side.
2. Integrate with the official dsh web. The recommended workflow is to first start the official host, then launch the TUI. The grok-dsh setup command writes the grok-server configuration to ~/.dsh/profiles/web/cordis.patch.yml and symlinks the plugin into that profile’s node_modules, so that npx @deepseek-ai/dsh web will include the leader socket. The compatibility documentation states that starting from version 0.2.0, it is recommended to run the plugin within the official host process instead of relying on a separate long-running backend.
3. Share sessions with the Web UI. The backend writes to the same session storage (default: ~/.dsh/sessions). Sessions created on the Web side will appear in /resume in the TUI, and sessions opened in the TUI will also show up on the Web side. Workspace grouping aligns with the Web’s workspace registry based on the session’s working directory. Do not drive the same session simultaneously via both Web and TUI: appends from both sides will interleave; the documentation notes that the server will attempt to repair interleaved logs when resuming, but you should avoid concurrent access in daily use.
4. Usage metrics without compiling grok yourself. The official grok binary can display token usage in the status bar (e.g., a context bar showing 18K/1.0M). More comprehensive metrics—cache hit rate, TTFT, TPS, cumulative input/output tokens—will automatically appear in the herdr pane or tmux. The README explicitly states that you do not need to compile grok source code for either of these. The herdr sidebar configuration is automatically written during installation and takes effect after restarting herdr or reloading the config.
5. In-terminal controllable operations. The architecture documentation records the connected pager-side operations: Ctrl+M or /model to switch models (the list comes from dsh’s provider directory); press Enter to allow a permission dialog once, Esc to reject; /resume to open the session selector; Ctrl+T to open the todo panel; /exit to quit the TUI. Slash commands follow grok pager’s built-in ones, and the plugin will not advertise dsh’s host command directory separately.

Installation and Activation¶

First meet two prerequisites: dsh is already installed on your machine, and the grok TUI binary is available. The grok installation command comes from the grok-build repository, for macOS / Linux:

curl -fsSL https://x.ai/cli/install.sh | bash

You can use the official quick start command for dsh:

npx @deepseek-ai/dsh web

The installation command provided by the community directory page, run in the DeepSeek Harness terminal:

dsh plugin add github:chen-001/dsh-grok-tui

For reproducible installations, pin the commit hash as instructed on the directory page:

dsh plugin add github:chen-001/dsh-grok-tui#commit

Replace #commit with the actual commit SHA. The directory page also reminds users: 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.

Simply running dsh plugin add is not enough to get a runnable grok-dsh command. The repository README provides two alternative activation methods with consistent post-install behavior (commands, automatic herdr sidebar configuration, metrics panel).

Method A: npm published version

npm install -g dsh-grok-tui
grok-dsh setup
npx @deepseek-ai/dsh web
grok-dsh

The meaning of each step is as follows:
- npm install -g dsh-grok-tui: Install the global package to provide the grok-dsh launcher.
- grok-dsh setup: Explicitly mount the bridge into dsh’s web profile. The README emphasizes that a global install will not silently modify dsh’s configuration, and you need to run this command yourself; it is idempotent and can be executed repeatedly.
- npx @deepseek-ai/dsh web: Start the official host. If the host is already running, you need to restart it after reinstallation for the leader socket to take effect.
- grok-dsh: Open the TUI and connect directly to the running dsh web instance.

Method B: Full git installation

git clone https://github.com/chen-001/dsh-grok-tui.git
cd dsh-grok-tui && sh install.sh

This installation script will automatically complete the same bridge mounting, then build and add grok-dsh to your PATH.

Typical Usage¶

The recommended order: start the official host first, then launch the TUI.

dsh web
grok-dsh

grok-dsh will detect a running dsh web instance and connect directly; otherwise, it will start a standalone backend in the current window. Supporting subcommands are as follows:

grok-dsh stop      # Stop all standalone backends
grok-dsh status    # View host bridge / standalone backend status and grok version
grok-dsh restart   # Restart the standalone backend in the current window

The working directory of the session will be the directory where you execute grok-dsh. Do not run both the standalone backend and dsh web at the same time: they will write to the same session storage.

The architecture documentation also records several environment variables suitable for per-project overrides instead of modifying global defaults:
- DSH_GROK_MODEL: Initial model, the documentation default is deepseek-v4-pro, a lighter alternative is deepseek-v4-flash
- DSH_GROK_EFFORT: Inference effort, the documentation default is max, optional values are off|high|max
- GROK_BIN: Specify the path to the grok / pager binary

When running grok-dsh in a herdr pane, the following real-time metrics will appear under the grok entry in the left agents list:

When running in tmux, a metrics panel will automatically open below the TUI, which can be closed by pressing q. The panel content includes cache hits, input / output / total tokens, API calls, and tool time. These numbers come from sample interfaces in the plugin documentation and are used to explain field meanings, not actual test results.

Applicable Scenarios and Notes¶

This plugin is suitable for the following use cases: users already using dsh as their primary Harness but prefer working in the terminal; users who want the Web UI and TUI to access the same session; users who need to monitor cache hit rates, TTFT, and TPS in herdr or tmux. This plugin is not a good fit if you mainly use dsh in a browser, or need Windows native named pipe support.

Treat the following points as hard constraints rather than optional recommendations:
1. Permissions and source. 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. grok-dsh setup / install.sh will modify ~/.dsh/profiles/web/cordis.patch.yml and symlink the plugin—this is an explicit operation, but it changes your local dsh configuration.
2. Platform support. The README states that macOS / Linux are supported. The architecture documentation notes that Windows named pipe is not implemented, and leader communication currently only supports Unix socket.
3. Do not use shared storage concurrently. Do not run both the standalone backend and dsh web at the same time; also do not drive the same session simultaneously via both Web and TUI.
4. This is a thin adaptation layer. The plugin connects two independently evolving projects: grok-build’s compiled client, and dsh which is still in developer preview. Mismatched leader protocol versions will cause connection failures directly; when some of grok’s private extension fields change, the main impact is degraded UI functionality (missing status bar, missing todo panel) rather than corrupting the session. After upgrading grok or dsh, you should re-verify compatibility per the repository’s COMPATIBILITY.md.
5. No extra authentication for the leader socket. The architecture documentation states that any local process that can connect to this socket can drive the Harness, with protection relying solely on the socket path permissions. This matches grok pager’s own leader behavior, but you should exercise caution on shared machines.
6. Project attribution. This plugin is a community project and not an official product from DeepSeek or xAI. grok-build itself is licensed under Apache-2.0; dsh-grok-tui is licensed under MIT. Inclusion in the directory page does not equal official endorsement.

Summary¶

dsh-grok-tui does not build a separate terminal Agent, but connects grok-build’s TUI to dsh’s existing prompt system, tools, routing, and session management. For users already using DeepSeek Harness and familiar with grok’s full-screen terminal experience, this is the shortest path to their desired workflow.

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

GitHub: https://github.com/chen-001/dsh-grok-tui

DeepSeek Harness: https://github.com/deepseek-ai/deepseek-harness