Preface¶

DeepSeek Harness (DSH) packages runtime capabilities like Agent Loop, tools, Session, and permissions into pluggable bundles. However, day-to-day development often still requires an interface within the terminal to handle conversations, approvals, and session management. While a web or headless profile can run through the workflow, it may not be ideal for long periods of staring at the Transcript, switching Sessions, or interacting with the Agent while editing code.

dsh-pi-tui is a third-party client plugin maintained by XMoon. Based on a vendored fork of Pi TUI, it is installed as a standalone bundle into a profile, specifically responsible for the terminal interaction layer. Capabilities like the model, tools, Session persistence, Skills, Plan, Goal, and Subagent are still provided by DSH; the TUI handles streaming display, keystrokes, Slash Commands, and the status line. Below, we introduce its positioning, core capabilities, and installation usage.

What is this¶

@xmoon76/dsh-pi-tui (community directory name xmoon/dsh-pi-tui) is an MIT-licensed npm package, currently at version 0.3.4. The README positions it as a “Pi TUI-based terminal frontend for DeepSeek Harness” — the installation package includes the necessary Pi TUI fork, so users do not need to install the internal TUI package separately.

The plugin is classified as a “client.” Its GitHub repository XMoon/dsh-pi-tui has about 11 stars. It has no official affiliation with DeepSeek / High-Flyer; the community directory SkillHub is an independent plugin collection site. The DSH ecosystem follows a “everything is a plugin” philosophy, and the directory site is not equivalent to an official app store.

Conversation, Focus, and Tool Display¶

The TUI side covers the visualization and interaction needed for daily conversations:

1. Streaming Markdown output, with collapsible Thinking (Alt+T) and Tool Calls displayed as cards showing running status.
2. Tool / System details are collapsed by default; Ctrl+O expands them. In full-screen Focus mode, Ctrl+O switches to toggling recent Thought roots.
3. Full-text search in the Transcript (Ctrl+F), with long conversation histories collapsible.
4. The status area displays Context, Token, model, and running status; supports Approval, ask_user_question, Plan Review, Todo / Goal display.

Focus Mode is entered with /focus: running Thinking, Tool Calls, and intermediate responses are aggregated into a real-time updating Thought block. When you need to see the process, you can expand it; closing Focus restores the normal Transcript. Focus only changes the interface projection and does not modify the events saved in the Session.

Session and Input History¶

The plugin integrates with DSH’s persistent Sessions, supporting creation and restoration, switching, renaming, Forking, Rewinding, Session lineage, and Transcript export. Common Slash Commands:

/sessions
/fork
/rewind

When idle and the editor is empty, pressing Esc twice quickly also opens Rewind. Rewind creates a new Child Session from the selected historical User Turn and places the corresponding Prompt back into the editor; the original Session is not modified.

Input history is searched with Ctrl+R, with selectable scope: Current session, Current directory, or All directories. Results include the Prompt, working directory, time, and Session information; selecting one restores it to the editor without sending it immediately. ↑ / ↓ is still used to browse recent inputs.

Subagent, Shell, and File References¶

/tasks opens the task browser for the current Session. Subagents are displayed in a full lineage tree (including nested descendants) and distinguished by continuable, one-shot, running / inactive, nested descendants, and background jobs. Completed one-shot Subagents still have their persistent Transcripts viewable. For direct continuable Children of the current Session, you can enter an interactive Viewer and continue sending messages; deeper nested Subagents are read-only by default.

Shell has two editor modes (! / !! are mode switches, not regular text prefixes):

! git status

Executes a local command, with output entering the current Session.

!! git status

Executes only locally, with output not entering the model context.

Inputting @ allows searching and completing workspace files, e.g., @src/index.ts or @"path with spaces/file.ts"; resolvable relative paths are converted to explicit file paths upon submission. Ctrl+V can paste clipboard images, which are saved to the Session via DSH Attachment.

Settings, Footer, and Shortcuts¶

Model and runtime settings follow DSH services. Common entry points include /model, /settings, /login, /permission, /plan, /goal, /compact, /footer, and /statusline. Slash Commands registered by other plugins to ctx.commands are automatically discovered. In /settings, you can switch Icon style (Emoji / Symbols / Minimal).

The Footer is a composable status surface. The Status line in /settings or the footer key in the settings document can be set to default (formerly full), compact, or custom; the command mode can only be enabled via USER layer settings documents. /footer provides an interactive configurator; footerLayout supports left-right areas, separators, and various built-in item IDs. With footer: command, the status snapshot is written to the user command’s stdin as JSON, and the stdout is sanitized and rendered; only commands configured in the USER layer will execute; footerCommand provided by repository/project layers will not execute.

Summary of common shortcuts (complete table in TUI’s /help):

Shortcuts can be overridden in the dsh-pi-tui settings namespace by semantic action (app.*). After changing, execute /keybindings reload to take effect. Environment variable DSH_PI_TUI_SAFE_KEYBINDINGS=1 ignores all user overrides.

Extension API¶

Besides being a terminal frontend, the package provides a versioned Extension API for other Cordis / DSH plugins to extend the interface. Public entry points include:

Extensible areas include Header / Footer, Input Widget, Slash Commands, Theme, Message / Tool Renderers, Overlay, etc. Plugins only need to depend on the public entry points and do not need to import the internal TuiApp implementation. The Stable API also supports contributing configurable Footer items via the chrome.footer.item slot.

Installation and Enabling¶

Environment requirements:

• DeepSeek Harness installed
• Node.js ^22.19.0 || >=24

The project currently develops against the DeepSeek Harness 0.1.1-rc.x version line. It is recommended to install and start using a separate pi-tui profile:

dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui
dsh --profile pi-tui

Restoring an existing Session:

dsh --profile pi-tui --session <session-id>

Updating, listing, uninstalling:

dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
dsh plugin --profile pi-tui -- list
dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui

After the above steps, the TUI can coexist with other Surfaces under the same runtime data, e.g., dsh --profile web, dsh --profile headless, dsh --profile pi-tui.

Use Cases and Considerations¶

Suitable for developers who need to use DSH for long periods in the terminal and want streaming Transcript, Session management, Subagent browsing, and Shell integration all within the same interface. If you primarily use the Web UI or scripted headless, you do not need to force a switch to the TUI; but if you want full interaction in the pi-tui profile, this bundle is the terminal frontend solution recommended by the README.

Please note before installation: the plugin runs with the current dsh process permissions. Shell mode (!) submits command output to the Session; footer: command only executes user-configured scripts under USER layer settings. Before installation, you should read the source code and the MIT License to confirm it meets your security and compliance requirements. The SkillHub directory page and GitHub repository are two entry points for the same plugin; the installation command should follow dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui in the README, rather than manually constructing github:owner/repo format based on the repository name.

dsh-pi-tui connects Pi TUI’s terminal experience to the DSH runtime: interaction in the TUI, capabilities in the Harness. For further understanding of the architecture, Extension API, or performance baseline, refer to the repository’s docs/ directory and the Extension API documentation.

• Community directory: https://www.skillhub.cn/plugins/XMoon/dsh-pi-tui
• GitHub: https://github.com/XMoon/dsh-pi-tui