Preface¶

DeepSeek Harness (command name dsh) splits the agent runtime into composable plugins: models, tools, sessions, sandboxes, and interfaces can all be added or removed on the Cordis kernel. The official developer preview page summarizes this as Everything is a plugin. The accompanying interactive entry point is the Web UI (dsh web / --profile web), while one-off tasks use the headless profile. For persistent terminal conversations, the official installation does not include a built-in interactive TUI.

The CLI reference documentation once used github:deepseek-harness/turtle-ui as an example of a profile bundle package. This organization repository currently returns a 404. Harness maintainer turtle1999 clarified in the discussion forum: that was a private repository that was never made public, and the TUI’s positioning will be reconsidered later; the publicly available repository is turtle1999/turtle-ui. The repository README states that it is “the first version of the dsh UI made on a Friday afternoon”, with content sourced from the original packages/ui/tui. The community directory categorizes it under “Interface Enhancements”, with the description “Original turtle UI project (provided as-is, no warranty)”.

A preliminary note: the directory pages referenced below are from the independent community site DeepSeek Harness Plugin Repository, which has no official affiliation with DeepSeek / Fangjia, and should not be treated as an official app store. The official repository is deepseek-ai/deepseek-harness. This article cross-references directory details, GitHub READMEs, package.json, cordis.patch.yml, source code, official CLI references, and discussion thread #871, with a verification date of 2026-08-18.

What is this¶

turtle-ui is an interface enhancement plugin maintained by turtle1999. Its npm package name remains @deepseek-ai/dsh-tui, with "private": true in package.json, so it is not published to the public npm registry and must be installed via Git. The license is BSD-3-Clause, and the LICENSE copyright line reads Copyright (c) 2026, DeepSeek. The GitHub repository description is as is, no warranty; the directory page labels it with 6 stars at the time of writing, while the repository page shows 7 stars.

It solves a specific problem: adding a terminal frontend to dsh. Its scope of responsibility is clearly defined in the README — the TUI only handles terminal rendering and input; agents, models, tools, persistence, and the dsh launcher remain the responsibility of Harness. Technically, it is a profile bundle package: package.json declares "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }, and when installed into a profile, it automatically applies a patch layer on top of @deepseek-ai/dsh-base, binding the TUI and the configured agent to the same persistent session.

Rendering relies on a patched version of @earendil-works/pi-tui. The repository lists it under devDependencies, bundles it into lib/ during build, so end users do not need to install pi-tui separately or configure patchedDependencies.

Core Features¶

The capabilities below are sourced from the README, cordis.patch.yml, and src/, and are not a product marketing list.

Terminal Session Frontend
Starts a conversation in the current TTY. Reasoning block display is enabled by default (showReasoning: true), and tool card collapsed preview retains up to 6 lines by default (maxToolOutputLines: 6). The status bar template can include the working directory, git worktree, model, cache hit rate, and context usage.
Session Identity Determined by Startup Parameters
The tui-startup module parses parameters passed by the launcher to the application, providing the tuiStartup service; the agent-loop and TUI line inject this service before evaluation to avoid opening the wrong session. --help only prints help information and does not start the agent. --resume and --session cannot be passed simultaneously.
Slash Commands and Shortcuts
Commands registered in the source code include:
- /help: Lists shortcuts and commands
- /model [[provider/]model]: Views or switches the model for the current session
- /clear: Clears the transcript view, preserving session history
- /details [collapsed|expanded|hidden] [reasoning [on|off]]: Adjusts tool card visibility and reasoning display
- /palette: Shows the color palette used in the terminal
- /status: Displays session diagnostics, system prompts, and registered tools
- /resume: Lists recoverable sessions in the current workspace
- /reload: Experimental feature, reloads loader configuration when idle
- /exit, /quit: Exits after the current turn is idle
- /skill: [instructions]: Loads skill instructions into the conversation (intercepted outside the command registry)

Shortcuts listed in the help text: Enter to send; Shift/Alt+Enter for newlines; Up/Down arrows to scroll through input history; Esc to cancel the current turn; Ctrl+O to cycle tool card collapse/expand/hide; Ctrl+R to toggle reasoning blocks; Ctrl+L to redraw; Ctrl+C to cancel during execution, clear input or exit when idle; Ctrl+D to exit.

Agent Layer Defaultly Stacked on dsh-base
The built-in patch modifies agent-loop, system-prompt, llm-deepseek, fs-sandbox, and tools, and inserts session references, storage, projection caches, tmux context, the TUI itself, and tool-ask-user. The default model is deepseek-v4-pro, with provider deepseek-official, API key environment variable DEEPSEEK_API_KEY, thinking: enabled, reasoningEffort: max, and tool mode native. These are the bundle’s default values, and the profile’s own cordis.patch.yml can overwrite the entire configuration block.
@ File Completion
The configuration includes limits for workspace file indexing, result count, and excluded directories, for fuzzy searching with @ in the editor.

One documented gap: The in-app /resume process handoff and exit prompt text still depend on the now-removed TUI-specific launcher, and are currently unavailable. /resume can list recoverable sessions; to actually switch sessions, use the command line’s --resume <sessionId>.

Installation and Activation¶

The installation command given on the directory details page is:

dsh plugin add github:turtle1999/turtle-ui

This is a bundle package, so it needs to be added to a profile. The web / headless profiles are automatically initialized with included templates; other names (including tui) will only install @deepseek-ai/dsh-base on first use. Both the repository README and official CLI reference use --profile tui as the example. A verified working syntax from the discussion forum is:

dsh plugin --profile tui add github:turtle1999/turtle-ui

Do not copy github:deepseek-harness/turtle-ui from the README and CLI reference verbatim. The GitHub API returns 404 for that path; using that command in #871 will fail during the git ls-remote stage. turtle1999’s publicly available repository is turtle1999/turtle-ui.

Installing from Git pulls the source code, then runs prepare (tsdown.prepare.config.ts) to build lib/ locally without type checking. pnpm ≥10 blocks this script by default. The first add will fail and print an allowBuilds key; add the printed key to the profile’s pnpm-workspace.yaml before running the command again. The official documentation interprets this approval as: allowing the package code to be executed locally during installation, not within the agent sandbox. Do not guess the key name.

For reproducible installations, pin the commit per the directory page:

dsh plugin add github:turtle1999/turtle-ui#<commit>

For local development, the README requires placing this repository and DeepSeek Harness as sibling directories, first building Harness, then building turtle-ui, then installing it into the profile using file: to have peer dependencies fall back to the profile’s hosted versions:

(cd ../deepseek-harness && pnpm install && pnpm run build)
pnpm install
pnpm run build
dsh plugin --profile tui add file:.
dsh --profile tui

package.json specifies Node ^22.19.0 || >=24.0.0, and packageManager as pnpm@11.7.0. After rebuilding, run add again to refresh the copy in the profile.

Typical Usage¶

After installation, start with:

dsh --profile tui

Without session parameters, a new session ID is generated each startup. Specify a new session ID or resume an existing one:

dsh --profile tui --session review
dsh --profile tui --resume <sessionId>
dsh --profile tui --help

The --help output matches the example in startup.ts. Once in the TUI, use /help to view shortcuts, /status to view session, token, and tool information, and /model to switch models. To modify interface behavior, do not edit files inside the package; overwrite the tui configuration block in the profile’s cordis.patch.yml. The patch replaces the entire config object, not performing a deep merge, so include all required keys when overwriting.

Model calls require DEEPSEEK_API_KEY. The llm-deepseek patch also reads DEEPSEEK_BASE_URL. The credential resolution order follows the official CLI reference: inherits environment variables, $DSH_HOME/.credentials.yaml, .env in the working directory, and $DSH_HOME/.env.

Use Cases and Notes¶

Suitable for users already using dsh who want to avoid opening a browser and monitor agents via SSH or local terminal. It is not an alternative to other community TUI projects (such as dsh-TUI in the directory, or @tomowang/dsh-tui on npm), which are independent implementations; turtle-ui is the original terminal layer extracted from Harness, and both the directory and repository release it under “as-is, no warranty”.

Important pre-use notes:
1. Permissions. The plugin runs with the permissions of the current dsh process, and may execute code during installation (including the prepare script). Inspect the source code and license before installing.
2. Outdated Documentation. The official CLI reference and this repository’s README still reference github:deepseek-harness/turtle-ui. Use the accessible turtle1999/turtle-ui repository as the source of truth.
3. Unfinalized TUI Positioning. The maintainer noted in #871 that the TUI’s positioning will be reevaluated. The API and package structure may change alongside Harness previews.
4. Resume Sessions via Command Line. In-app /resume process handoff is unavailable; resume sessions using dsh --profile tui --resume <sessionId>.
5. Environment Requirements. An interactive TTY, installed dsh CLI, and pnpm in PATH are required. Peer dependencies target multiple @deepseek-ai/dsh-* ^0.0.1 and @deepseek-ai/cordis ^4.0.0-rc.7. If versions do not match the current Harness setup, prioritize checking version compatibility instead of modifying the TUI source code.

Summary¶

turtle-ui repackages the early terminal UI of DeepSeek Harness as a bundle package: without modifying the launcher, it applies a patch layer on top of a profile to let agents run in a TTY. Both the directory page and repository state that it is provided as-is with no warranty; use the installation address github:turtle1999/turtle-ui, not the now 404 deepseek-harness/turtle-ui.

Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/turtle-ui/
GitHub: https://github.com/turtle1999/turtle-ui

Use turtle-ui to open the original TUI of DeepSeek Harness in the terminal