Skip to content

dsh-opentui

Verified

@aiwayds/dsh-opentui · v0.6.1 · Apache-2.0

A next-generation TUI **platform** for [dsh](https://github.com/deepseek-ai/dsh) — new architecture, not a reskin of dsh-tui-pi. Built on [OpenTUI](https://github.com/anomalyco/opentui) + [Solid](https://solidjs.com), running on Bun.

Install

dsh plugin add @aiwayds/dsh-opentui

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Readme

dsh-opentui

A next-generation TUI platform for dsh — new architecture, not a reskin of dsh-tui-pi. Built on OpenTUI + Solid, running on Bun.

The repo's product is the architecture; the shipped Shell is a working chat agent TUI on top of it:

Package What it is
@dsh-opentui/runtime Engine lifecycle, cordis surface service, stdout capture, protocol types
@dsh-opentui/kit Shared components: theme tokens, t() i18n seam, status bar, panel, line
@dsh-opentui/shell Usable chat TUI: ask → thinking stream → tool approval → reply
starter/ Copyable plugin template; consumes the surface protocol with zero build step

See CONTEXT.md for the glossary and docs/adr/ for decisions: Solid (0001), two integration channels with no compat shim (0002), Bun + compiled binary distribution (0003), host profile route (0004).

Install

Prerequisites:

  • The dsh host: npm i -g @deepseek-ai/dsh (or your official channel)
  • Node >= 26.4 (OpenTUI's native core needs --experimental-ffi, injected for you)
  • pnpm
npm i -g @aiwayds/dsh-opentui
dsh-opentui

The first launch idempotently installs a dsh profile at ~/.dsh/profiles/dsh-opentui (bundles: dsh-base + this package) and pins the default model through a cordis patch (llm-pi-ai provider routing + agent-default-model: zai-coding-cn/glm-5.3-flash/high). Afterwards dsh-opentui is equivalent to dsh --profile dsh-opentui.

To change the model, re-run the installer with flags (--provider / --model / --reasoning-effort) or edit the profile's cordis.patch.yml directly.

Prefer to run without the host? See Direct mode (development).

Run as a dsh profile (host mode)

The Shell runs inside the real dsh host as a profile. The dsh-opentui bin handles everything: on first launch it installs the profile, then it execs the host with the profile flag and injects --experimental-ffi for you. After the first run, dsh-opentui is equivalent to:

NODE_OPTIONS=--experimental-ffi dsh --profile dsh-opentui   # manual fallback
What Where
Profile ~/.dsh/profiles/dsh-opentui (bundles: dsh-base + @aiwayds/dsh-opentui; model pinned via cordis.patch.yml)
Runtime node >= 26.4 with --experimental-ffi inside the host (auto-injected by the bin)
Model & keys reused from the host's own config; override the pinned default via installer flags or the patch file

Direct mode (development)

Without the host, useful for hacking on the Shell itself:

cd ~/repo/dsh-opentui/packages/shell
bun src/main.tsx                      # dev run
bun src/main.tsx --model zai-coding-cn/glm-5.2   # explicit model
bun build.ts && ../../build/dsh-opentui-darwin-arm64   # standalone binary

Config reuse: the Shell reads your existing dsh config — model default comes from ~/.dsh/model-profiles.json (current profile's workhorse agent), provider baseUrls from ~/.dsh/models-store.json, API keys from ~/.dsh/.credentials.yaml. Override with --model provider/id or DSH_OPENTUI_MODEL / DSH_OPENTUI_API_KEY.

In the TUI: type a question, Enter to send. The model's thinking streams dim; tool calls (bash / read_file / write_file) pop an approval card — y allow, n decline; esc aborts a running turn. Ctrl+C interrupts a running turn and shows "Press Ctrl+C again to quit"; a second Ctrl+C within 500 ms quits (client mode). Commands: /help /model [provider/id] /usage /clear /quit.

Plugin integration, 30 seconds

Layer 2 (declarative, zero build) — inject the surface service:

import type { Context } from "@deepseek-ai/cordis"
import { hasSurface } from "@dsh-opentui/runtime"

export function apply(ctx: Context) {
  if (!hasSurface(ctx)) return // headless: no surface host mounted
  ctx.surface.declare({
    kind: "widget", slot: "status", id: "myplugin.state",
    parts: [{ text: "myplugin", dim: true }, { text: " ok", color: "#50fa7b" }],
  })
}

Layer 1 (Solid components) — depend on @dsh-opentui/kit and write components; add vite + babel-preset-solid to your build.

Develop

npx [email protected] install
cd packages/shell && bun src/main.tsx   # run the shell
bun test                                # tests (repo root)
npx [email protected] -r typecheck

To test host mode against local sources, point the installed profile at the repo via link: mounts, then rebuild after changing plugin sources:

cd packages/shell && bun build-host.ts

Requires Bun >= 1.3.14 (bun upgrade). Note: each package carries its own bunfig.toml (the @opentui/solid preload) — bun only reads the CWD's bunfig; a root-level one breaks compiled binaries ("preload not found").

Verification gates (client mode, live)

node packages/shell/scripts/e2e-sweep.mjs   # full command-surface sweep
node packages/shell/scripts/e2e-client.mjs  # two-process topology gate (attach/adopt/reload)
node packages/shell/scripts/e2e-live.mjs    # in-process live gate
node scripts/smoke-boot.mjs                 # boot smoke

e2e-sweep.mjs drives EVERY slash command + keyboard surface through the real client topology in tmux 120x34 (slow typing, per-item capture): the read-only commands, every overlay picker, /config forms, the /login panel + headless forms, the palette / history-recall / alt+enter / paste / scroll / dock-toggle / esc stop-confirm keys — and the keystroke-leak regressions (modal-consumed keys must never type into the blurred editor). It runs under a scratch DSH_HOME (temp dir, mode 700) seeded from the real profile, so login/logout/config/preset writes never touch the user's home. Real turns ride the workingRoute pattern: the catalog is probed, a route is selected, and when no route answers the turn items report BLOCKED loudly while everything else still gates. Per-item captures land in a temp caps dir for eyeballing. Requires dsh, tmux, bun on PATH; otherwise the script self-skips (exit 0) so CI runs green.

Status

v0.1.0: published as @aiwayds/dsh-opentui (host profile mode via the dsh-opentui bin, direct-mode binary). Roadmap: host seams (approval waterfall, ask, attachments, sessions via the real dsh host) · full Kit + starter polish · linux binary release pipeline.