deepseek-harness-tui

This fork — maintained by Auth Tecnologia as the base of a complete terminal interface for the DeepSeek Harness: see ROADMAP.md. Originally written by gxinxing, MIT; the name is provisional.

An interactive terminal chat for DeepSeek Harness — terminal-native style, built with Ink (React for terminals).

Give it a TokenDance key and a dsh install; run dsh --profile tui and you get a zero-chrome terminal chat with DeepSeek models: bottom-anchored transcript, tool calls folded into cells, thinking folding, and a theme that adapts to your terminal via OSC 11. It's a thin, readable plugin (~800 lines of UI) — not a re-implementation of the harness.

English · 简体中文

Install

On Linux or macOS, one line — no sudo, everything in your home folder:

curl -fsSL https://auth-com-br.github.io/dsh-tui/install.sh | sh

It uses your Node.js 20+ (or puts the official one in ~/.local/share/dsh-tui), installs the harness with it at the version this TUI is tested on (the harness's 0.2 series changed its API and does not run it yet), wires its tui profile to this TUI, and adds two commands to ~/.local/bin: dsh, which opens the TUI with no --profile (the harness's own dsh web, dsh plugin … and dsh --profile … pass through), and dsh-tui. Run it again to update. Then dsh, and /models to choose a model. The page: https://auth-com-br.github.io/dsh-tui/ — the installer: docs/install.sh.

By hand

Requires Node.js ≥ 20 and the DeepSeek Harness CLI:

npm install -g @deepseek-ai/dsh        # the harness (no Homebrew tap yet)
git clone https://github.com/gxinxing/deepseek-harness-tui
cd deepseek-harness-tui && pnpm install

Wire the plugin bundle into the tui profile (one-time):

dsh plugin --profile tui add @deepseek-ai/dsh-headless
dsh plugin --profile tui add /path/to/deepseek-harness-tui

Use

export TOKENDANCE_API_KEY=sk-...   # or add it to ~/.dsh/.credentials.yaml (0600)
dsh --profile tui                  # open the TUI

In the TUI: a drag selects text in the conversation alone — not the side panel, not the composer — and copies it when you let go, as OpenCode does; ctrl + v attaches the image on the clipboard, and pasting or dropping an image file attaches it (for a model that takes images); /copy copies the last answer whole (/copy 2 the one before). The wheel and ↑/↓ scroll, ctrl + ↑/ctrl + ↓ recall earlier messages, a click (or ctrl + t) opens or folds a thought, esc interrupts the running turn, /help shows all keys and commands. /mouse off gives the mouse back to the terminal and its own selection.

What it does

• Terminal-native UI, not a re-skinned echo. The transcript is the surface — no boxes, no chrome. The DeepSeek brand banner (ANSI Shadow logo, gradient) greets you only on the empty state; model · cwd live in a dim footer.
• Tool calls fold into cells. ⠋ Running <cmd> while active → ✓ <cmd> • 1.2s (or ✗ on error), with output merged into the cell, dimmed, and truncated head + tail (… +N lines). No interleaved wall of raw output.
• Theme derived from your terminal. OSC 11 probes the real background: message tints and code chips are blended from it (12% white over dark, 4% black over light) — never hardcoded hex. Force a theme with DSH_TUI_BG=#ffffff for testing.
• Thinking you can fold. ctrl + t toggles the reasoning trace; esc aborts the turn at any time via agent.cancel({ kind: 'user' }).
• Markdown that keeps its shape. Headers keep their #, fenced blocks keep their fences, inline code gets a subtle chip — and CJK/emoji wrap at correct character widths with an aligned gutter.
• A live viewport. The transcript is bottom-anchored; the tail is always visible. Busy state shows a braille spinner + compact elapsed timer (Working 5s).

Learn more

• INTEGRATION-NOTES.md — event shapes, patch semantics, and the integration deep-dive (how session/event maps to the UI)
• DeepSeek Harness — the underlying agent framework
• Model routing (TokenDance) — gateway config, credentials, and the one-time tool-call guard

Model routing (TokenDance)

The profile patch (cordis.patch.yml) routes llm-deepseek through the TokenDance gateway:

llm-deepseek:
  apiKeyEnv: TOKENDANCE_API_KEY
  baseURL: https://tokendance.space/gateway/v1

The provider is registered in ~/.dsh/settings.yaml (llm-pi-ai.providers.tokendance): OpenAI-compatible endpoint, thinkingFormat: deepseek, models deepseek-v4-flash (default) and deepseek-v4-pro. Switch models by editing the provider's models list or overriding llm-deepseek.model in your profile patch.

Prerequisite fix (one-time, per dsh install). TokenDance streams subsequent tool-call deltas with empty name/id; the stock @deepseek-ai/dsh-llm-deepseek adapter overwrites the first frame's call id with "" and the harness loops on unknown tool "". Apply the guard in node_modules/@deepseek-ai/dsh-llm-deepseek/lib/index.js:

- if (call.id !== void 0) block.callId = call.id
+ if (call.id) block.callId = call.id
- ... if (call.function?.name !== void 0) ...
+ ... if (call.function?.name) ...

Applied 2026-08-13 on this machine. The edit lives in the global dsh install and is lost on dsh upgrade — re-apply after upgrading (worth an upstream PR).

Self-inspection · Self-repair · Self-update loop

This project ships a complete automated quality gate — inspect → repair → update — closed loop:

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Local dev   │    │  Pre-commit  │    │  CI / PR     │
│  pnpm check  │───▶│  lint-staged │───▶│  ci.yml      │
│  (one-shot)  │    │  (git commit)│    │  (GitHub)    │
└──────────────┘    └──────────────┘    └──────────────┘
      ▲                                       │
      │                                       ▼
      │                            ┌──────────────────────┐
      │                            │  lint + format:check  │
      │                            │  + test (Node 20/22)  │
      │                            └──────────────────────┘
      │                                       │
      ▼                                       ▼
┌──────────────────────────────────────────────────────────┐
│          deps.yml  (auto-scan every Mon 06:00 UTC)        │
│  Update found → auto PR → review & merge → closed loop   │
└──────────────────────────────────────────────────────────┘

Local inspection

pnpm check        # all-in-one: lint → format:check → test
pnpm lint         # code quality (ESLint)
pnpm format:check # style gate (Prettier)
pnpm test         # unit tests (Node built-in runner, 57 cases)

Local self-repair

pnpm lint:fix     # auto-fix all fixable ESLint issues
pnpm format       # auto-format all source files

On every git commit (husky + lint-staged):

• staged *.js files → prettier --write + eslint --fix before the commit lands
• committed code is always clean — no manual pnpm format needed

Dependency self-update

pnpm deps:check   # scan all deps for available upgrades (grouped + audit)
pnpm deps:update  # bump package.json to latest compatible + pnpm install

GitHub Actions auto-runs (.github/workflows/deps.yml):

• Every Monday 06:00 UTC
• Creates a deps/auto-update-YYYYMMDD branch + PR when updates exist
• Manual trigger available from the GitHub Actions tab

CI gate (.github/workflows/ci.yml)

Trigger	Job	Matrix
push / pull_request to main	inspect	Node 20 + Node 22
	lint	✅
	format:check	✅
	test (57 cases)	✅
	coverage upload	Node 22 only

Any stage failure blocks the merge — main is always green.

Contributing

Issues and PRs are welcome. Good first tasks: upstream the two runtime patches (TokenDance tool-call guard, grep permission-error tolerance), add a screenshot for light themes, or port the welcome banner to other model providers. See INTEGRATION-NOTES.md before touching the event bridge.

License

MIT. An independent community project, not affiliated with DeepSeek or TokenDance.

Reminders (opt-in)

overlays/schedule.yml gives the model reminder tools (dsh-schedule), as the web app's Schedule overlay does: dsh --profile tui --patch overlays/schedule.yml for one run, or its insert copied into ~/.dsh/cordis.patch.yml for every run. /schedule lists them.