dsh-pi-tui

English | 简体中文

Release history: CHANGELOG.md · 简体中文更新日志

A third-party TUI mode for DeepSeek Harness (dsh), built on a vendored fork of pi-tui.

Run dsh --profile pi-tui for a terminal UI instead of the browser GUI (dsh --profile web) or one-shot mode (dsh --profile headless).

Status: working. The TUI covers the main session loop — input → session events, approvals, commands, session switching and full-text search — plus presets, skills, model/settings menus, and slash commands. Rendering and input routing are verified by headless tests (@xterm/headless) with no TTY or model connection needed.

Screenshot

Layout

The full repository layout lives in AGENTS.md (the contributor operating manual). In one line: packages/pi-tui/ is the vendored @moonshot-ai/pi-tui fork (rescoped to @xmoon76/pi-tui, private, never published — its divergence ledger lives in packages/pi-tui/AGENTS.md), and packages/dsh-pi-tui/ is the dsh bundle (@xmoon76/dsh-pi-tui, the only published package) that bundles the fork into its build output.

Prerequisites

• A DeepSeek Harness installation with profiles support (dsh on your PATH).
• Node >= 22.19 (^22.19.0 || >=24, same range as dsh). Running from source needs Node with native TypeScript support (>= 23.6) or the tsx ESM hook (node --import tsx/esm, how dsh's own source launch works).
• pnpm only when installing from source.

Install

dsh plugin runs pnpm inside the target profile's directory, so the usual pnpm verbs (add, remove, update, list) all work.

Option A — from the npm registry (recommended)

The published package is self-contained: the vendored pi-tui fork is bundled into its build output, so @xmoon76/dsh-pi-tui is the only package you install (@xmoon76/pi-tui stays private in this repo, like kimi-code keeps @moonshot-ai/pi-tui private):

# install the bundle into the pi-tui profile (creates the profile if needed)
dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui

# run it
dsh --profile pi-tui

Any dependency whose manifest declares dsh.bundle joins the profile's layer stack automatically — no manual cordis.patch.yml wiring.

Option B — from source

Build artifacts are not committed (dist/ for both packages is gitignored and the package exports point at the built files), so build before installing from a clone:

git clone https://github.com/XMoon/dsh-pi-tui
cd dsh-pi-tui
pnpm install
pnpm build        # pi-tui tsdown (dist/) + dsh-pi-tui tsdown (dist/, bundles pi-tui)

# file: — the bundle is copied into the profile at add time; rebuild + re-add
# to refresh (see "Update / uninstall" below)
dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@file:$PWD/packages/dsh-pi-tui

# link: — a live symlink instead; `pnpm build` output is picked up directly
dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@link:$PWD/packages/dsh-pi-tui

Verify the install

dsh plugin --profile pi-tui -- list          # @xmoon76/dsh-pi-tui present
dsh --profile pi-tui                         # TUI starts instead of the web GUI

Update / uninstall

# registry installs:
dsh plugin --profile pi-tui -- update @xmoon76/dsh-pi-tui
# file: source installs copy at add time — rebuild + re-add to refresh
# (link: installs track the repo live and need only `pnpm build`):
pnpm build && dsh plugin --profile pi-tui -- add @xmoon76/dsh-pi-tui@file:$PWD/packages/dsh-pi-tui

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

Development

pnpm install
pnpm build        # pi-tui tsdown (dist/) + dsh-pi-tui tsdown (dist/, bundles pi-tui)
pnpm test         # pi-tui's own suite (node --test) + dsh-pi-tui headless tests
pnpm typecheck
node --expose-gc packages/dsh-pi-tui/scripts/bench.mts   # performance baseline (optional)

Tests drive the UI through @xterm/headless (see packages/dsh-pi-tui/test/virtual-terminal.ts), so rendering and input routing are verified without a TTY or a model connection.

Development history (dogfooding)

This project started development on the browser surface (dsh --profile web) and switched to building itself with itself: since August 15 2026, all fixes and features are developed inside this TUI, the same way this README and the codebase are maintained. The dev loop runs on a dedicated pi-tui-dev profile installed with Option B's link: specifier (dsh plugin --profile pi-tui-dev -- add @xmoon76/dsh-pi-tui@link:$PWD/packages/dsh-pi-tui) — a live symlink, so pnpm build is picked up without re-adding — while the pi-tui profile stays on the published registry package for real use.

Slash commands (selection)

• /sessions [query] — open the session picker: search-as-you-type over session ids, titles, and workspaces, rows grouped by workspace with live filtered/total counts, and titles loaded in the background as they are read. Enter switches to the selected session.
• /search <query> — full-text search over persisted session logs, then switch to a hit.
• /title [title] / /rename [title] — with an argument, set the current session's title (pins it against automatic generation; titles appear in the /sessions picker); without an argument, regenerate the title from the conversation — this overwrites the current title, including one you pinned earlier.
• /yolo — switch to danger-full-access (alias of /permission danger-full-access).
• /queue — per-item queue management: edit, delete, steer one, or insert a message into the agent's inbox (the queue pane above the editor shows pending messages; Ctrl+S steers them all at once, Alt+↑ pulls them all back into the editor).
• /status — show the current session's stats and identity (turn counts, token usage, workspace, installed dsh version).
• /preset, /model, /settings, /export, /fork, /subagents — see dsh --profile pi-tui's command autocomplete (/ + Tab).

Keybindings (selection)

• Ctrl+F — toggle transcript search (the /search <query> overlay; a second press closes it).
• Shift+Tab — cycle the permission preset (read-only → workspace-write → danger-full-access); the footer's mode slot badges every preset ([workspace-write] / [read-only] / [custom], with [yolo] flagging the no-approval mode).
• Ctrl+S — steer: with queued messages, sends the whole queue (plus the draft, if any) into the running turn at once; otherwise sends the draft alone. An idle agent starts a fresh turn with everything.
• Alt+↑ — dequeue: pull every queued message back into the editor draft.
• Ctrl+T — toggle the full todo list; the dock above the editor always shows the todo summary and background tasks, and queued input renders between them.
• @ — file/folder mentions in the editor: @ + Tab completes files from the whole workspace (fd-backed when fd is on PATH, with a built-in recursive fallback otherwise). The literal @path is submitted and the model reads the file itself. With background work running, an empty editor's ↓ or Ctrl+J opens the task browser over both surfaces:
  • subagent rows (live continuable children) — Enter opens the child's transcript read-only (Esc returns); they never register jobs records, so this browser is their only glanceable home.
  • job rows (bash and one-shot subagent jobs) — Enter shows the status viewer only: a bash job's output read cursor belongs to the model's job_output, and a one-shot subagent job record carries no child session id, so the transcript is reached via /subagents (s stops a job). The footer badge shows [N tasks running · M agents · ↓ view] while any background work is live.

Launch options

The TUI's startup row adds --preset <id> — the agent preset a fresh session starts on (falls back to $DSH_PI_TUI_PRESET, then the saved settings default). It exists because /preset only applies to a blank (not yet created) session, so launch-time selection is the other half of choosing a preset. All other flags are the dsh runner's own (--session <id>, …).

Session lifecycle

Opening the TUI with no --session creates no session at all: the first user message (text, slash command, Ctrl+S steer, or ! shell) starts it lazily. --session <id> still resumes immediately, and a local !! command runs without needing a session.

Verified in the P0 spike

• Vendored pi-tui: the fork's own suite passes under node --test (run it as the sync gate after every re-vendor; the count is deliberately not copied here — packages/pi-tui/package.json is the single source of version facts).
• TuiApp renders, accepts editor input, and handles Ctrl+C on a headless xterm.
• The whole import chain (pi-tui, tui-app, @deepseek-ai/dsh-cmdline, commander) loads under the tsx ESM hook — the dsh source-launch contract.
• Native modifier-key addons are optional: on Linux the loader returns undefined without attempting a load, and the non-TTY stdin path is guarded.

Safety & operational notes

• One surface per session. dsh has no cross-process session coordination: a session open in TWO dsh processes (TUI + web, or two TUIs) can corrupt its log. The TUI refuses to open a session already held by another live dsh process (an owner.lock file next to the log, with a pid/starttime probe for stale locks left by crashes — so the second surface is stopped at OPEN time, not after the damage). For writes, the TUI detects the other writer and blocks the send; the SAME action pressed again (Enter for a submit, Ctrl+S for a steer, unchanged draft) forces through — an edited draft, a swapped key, a new file revision, or a session switch invalidates the force. Never run two surfaces on one session (full contract: docs/concurrency.md).
• Session repair. node_modules/@xmoon76/dsh-pi-tui/scripts/repair-session.mjs repairs corrupted logs (--scan lists damage read-only; --yes applies with a mandatory backup). A torn (truncated) tail is truncated at the last complete frame and reported with exact byte accounting; references to a duplicated seq are never auto-resolved — the repair refuses and asks for --duplicate-reference=first|last|segment. Repaired logs are re-verified with the dsh reader's own layout checks before the backup is considered redundant. (Full repair contract, incl. the frame-layout constraint: docs/repair-session.md.)
• Exit. /exit (alias /quit) flushes the session with a 10s hard timeout: a hung provider cannot trap the TUI. If the flush fails or times out, the terminal prints a warning (the tail may not be persisted) and the process still exits.
• Performance. scripts/bench.mts (non-default) measures ingest, projection, cold/warm rebuilds, streaming frames, theme switches, and heap; the saved baseline lives in docs/perf-baseline.md. Unchanged transcript messages reuse their rendered components, so the warm per-frame rebuild does not grow with history.

License

MIT. packages/pi-tui retains its upstream MIT license and authorship (Copyright (c) 2025 Mario Zechner; Moonshot AI fork).