dsh-tui-pi

KO | EN

gitlite — search

#postgresql #hacktoberfest #typescript #gpt #claude #gemini #large-language-models #ui #rust #llm

(★ 9)

A fully-featured pi-style terminal UI for DeepSeek Harness (dsh) — history look-back & fork-at-turn, guided preset switching, live subagent steering, model profiles & themes.

File Explorer

ZIP Download

- - ci.yml
  - release.yml
- - mcp.mp4
- - dsh-tui-pi-nerd.ttf
  - LICENSE-Hack.txt
  - LICENSE-NerdFonts.txt
  - LICENSE-NotoSansSymbols.txt
  - LICENSE-NotoSansSymbols2.txt
- deepseek-icon.svg
- fonts-gen.mjs
- whale-gen.mjs
- whale-source.png
- dsh-tui-pi
- preflight-projcache.mjs
- - 0001-btw-tui-owned-command.md
  - 0002-target-dsh-0.1.2-alpha.3-single-target.md
  - 0003-history-linear-list-not-tree.md
- - ask-user-question.md
  - dcp.md
  - feishu-demo.md
  - footer.md
  - history.md
  - mcp-adapter.md
  - model-profiles.md
  - persistent-context.md
  - preset-switch.md
  - search-selection-images.md
  - sessions-resume.md
  - slash-commands.md
  - startup-tree.md
  - subagents.md
  - themes.md
  - think-tool-panels.md
- design-steer-followup.md
- subagent-registry-plugin-design.md
- - common.sh
  - mock-llm.mjs
- - 10-install.sh
  - 20-start.sh
  - 22-search.sh
  - 30-commands.sh
  - 40-theme.sh
  - 50-resize-exit.sh
  - 60-preset.sh
  - 65-ux-batch.sh
  - 66-retention-resume.sh
  - 68-ask-user.sh
  - 69-btw.sh
  - 70-steer-injection.sh
  - 71-cache-hit.sh
  - 74-profiles.sh
  - 75-hard-stop.sh
  - run-all.sh
- Containerfile
- README.md
- run-e2e.sh
- dev-upgrade.mjs
- diagnose-container-tui.sh
- install-font.mjs
- link-dsh-closure.mjs
- repair-session-log.mjs
- smoke-boot.mjs
- - SKILL.md
- - index.ts
  - palette.ts
  - registry.ts
- activity.ts
- agent-manager.ts
- agent-runtime.ts
- agents.ts
- append-system.ts
- ask-user.ts
- attachments.ts
- btw-overlay.ts
- btw.ts
- canvas-terminal.ts
- clipboard.ts
- commands.ts
- custom-provider.ts
- dsh-events.ts
- editor.ts
- font-detect.ts
- footer.ts
- frame.ts
- git.ts
- history-fork.ts
- history-turns.ts
- history.ts
- host-version.ts
- hotkeys.ts
- icons.ts
- index.ts
- keymap.ts
- live-widgets.ts
- log-repair.ts
- login.ts
- messages.ts
- model-list.ts
- model-profiles.ts
- mouse-mode.ts
- notice-bridge.ts
- panels.ts
- permission.ts
- preflight-projcache.ts
- preset-dialog.ts
- preset.ts
- projcache.ts
- provider-catalog.ts
- queue-panel.ts
- quotes.ts
- reload.ts
- remote-tail.ts
- repair-dialog.ts
- retention.ts
- route-dialog.ts
- schema-model.ts
- selectors.ts
- session-dir.ts
- session.ts
- sessions.ts
- settings.ts
- skills-manager.ts
- skills.ts
- startup-info.ts
- steer-flow.ts
- stop-dialog.ts
- subagent-policy.ts
- subagent-status-tool.ts
- subagent-viewer.ts
- text.ts
- theme-preview.ts
- theme-settings.ts
- tokens.ts
- tui.ts
- usage.ts
- welcome.ts
- workspace-presets.ts
- - ArtyDuck.md
  - oldfox.md
  - workhorse.md
- APPEND_SYSTEM.md
- agent-manager.test.mjs
- agent-runtime.test.mjs
- append-system.test.mjs
- ask-user.test.mjs
- bridge-stop.test.mjs
- btw.test.mjs
- clipboard.test.mjs
- commands.test.mjs
- custom-provider.test.mjs
- dev-upgrade.test.mjs
- e2e-canvas-fixture.mjs
- font-detect.test.mjs
- footer-hints.test.mjs
- frame.test.mjs
- history-fork.test.mjs
- history-turns.test.mjs
- history-viewer.test.mjs
- history.test.mjs
- host-version.test.mjs
- hotkeys.test.mjs
- icons.test.mjs
- image-blocks.test.mjs
- install-font.test.mjs
- keymap.test.mjs
- live.test.mjs
- log-repair.test.mjs
- login.test.mjs
- markdown-latex.test.mjs
- messages.test.mjs
- model-list.test.mjs
- model-profiles.test.mjs
- mouse-mode.test.mjs
- notice-bridge.test.mjs
- panels.test.mjs
- pending-echo.test.mjs
- permission.test.mjs
- plugin-inject.test.mjs
- preflight-projcache.test.mjs
- preset-dialog.test.mjs
- preset.test.mjs
- projcache.test.mjs
- provider-catalog.test.mjs
- queue-panel.test.mjs
- quotes.test.mjs
- reload.test.mjs
- remote-tail.test.mjs
- repair-session-log.test.mjs
- repro-append-system.mjs
- repro-esc-leak.mjs
- retention.test.mjs
- schema-model.test.mjs
- selection-copy.test.mjs
- session-ch-cache.test.mjs
- session-dir.test.mjs
- session-reconcile.test.mjs
- sessions.test.mjs
- settings.test.mjs
- skill.test.mjs
- skills-manager.test.mjs
- skills.test.mjs
- startup-info.test.mjs
- steer-flow.test.mjs
- stop-dialog.test.mjs
- subagent-policy.test.mjs
- subagent-status-tool.test.mjs
- subagent-viewer.test.mjs
- text.test.mjs
- theme-canvas.test.mjs
- theme-picker.test.mjs
- theme-registry.test.mjs
- theme-settings.test.mjs
- theme-switch.test.mjs
- theme.test.mjs
- tokens.test.mjs
- transcript-search.test.mjs
- usage.test.mjs
- welcome.test.mjs
- workspace-presets.test.mjs
- ayu-light.json
- catppuccin-latte.json
- catppuccin-mocha.json
- dracula-light.json
- dracula.json
- github-dark.json
- github-light.json
- gruvbox-dark.json
- gruvbox-light.json
- material-light.json
- monokai.json
- nord-dark.json
- nord-light.json
- one-dark.json
- one-light.json
- solarized-dark.json
- solarized-light.json
- synthwave.json
- tokyo-night-light.json
- tokyo-night.json
.containerignore
.gitignore
agent-description-bug-report.md
AGENTS.md
ARCHITECTURE.md
CHANGELOG.md
CONTEXT.md
cordis.patch.yml
LICENSE
package.json
PLAN-skills-manager.md
PLAN.md
pnpm-lock.yaml
README.md
README.zh-CN.md
README.zh.md
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[English](README.md) | [简体中文](README.zh-CN.md)

A fully-featured pi-style terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) — a plugin suite that turns dsh into a pi-like coding-agent experience: /history look-back & fork-at-turn, guided preset switching, live subagent steering, model profiles, 20+ built-in themes (10 light + 10 dark) with user theme directory discovery, and a powerline footer.

**Requires dsh >= 0.1.5-rc.2** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.** A startup guard logs a one-line warning and exits cleanly when the host is older than the floor (opt out with `DSH_TUI_SKIP_HOST_CHECK=1`). See [ADR 0002](docs/adr/0002-target-dsh-0.1.2-alpha.3-single-target.md) for the now-superseded alpha single-target decision.

https://github.com/user-attachments/assets/67a7c6ca-ff42-4005-b543-437ba61771bb

*A live recording of a session (MP4, 1.5× speed) — todos, running subagents, think/tool panels and the powerline footer in action.*

## ✨ Features

> Each item links to its own doc under [`docs/features/`](docs/features/) — one line here, the details (and demo videos) there.

- [**Footer — live session overview**](docs/features/footer.md) — provider/model, context pressure and the session cache-hit rate at a glance, always in view.
- [**Think & tool panels**](docs/features/think-tool-panels.md) — reasoning and tool activity stay out of the transcript, so the conversation reads clean.
- [**Subagents**](docs/features/subagents.md) — every running subagent gets a status line; watch and steer it live.
- [**Ask User Question**](docs/features/ask-user-question.md) — the model can pause and ask you structured questions, answered without leaving the TUI.
- [**Feishu integration**](docs/features/feishu-demo.md) — dsh-tui-pi on the desktop and Feishu/Lark on the phone driving (and answering for) the same dsh session.
- [**Dynamic context pruning (DCP)**](docs/features/dcp.md) — context stays within limits automatically, with zero LLM calls.
- [**Persistent context**](docs/features/persistent-context.md) — your ground rules ride along on every request, hot-applied with no restart.
- [**Model profiles & favorites**](docs/features/model-profiles.md) — profile switching lives in [dsh-profile-switch](https://github.com/fan56/dsh-profile-switch) now; this suite keeps the TUI read side (session seeding from the pin, live-selection bridge, scope-aware `/agents` edits) and the `/model` favorites that keep the picker small.
- [**Agent preset switching**](docs/features/preset-switch.md) — `/preset` between the shipped agent compositions (`standard`, `minimal`, …); a switch is confirmed and starts a NEW session on the preset (the current one stays resumable); what a preset really gates.
- [**Sessions & resume**](docs/features/sessions-resume.md) — sessions stay tidy automatically and resume in a few keystrokes; the host's kernel write lease keeps the log single-writer across processes.
- [**History browser**](docs/features/history.md) — `/history` opens a fixed two-pane look-back over the session: completed turns on the left, the selected turn's replies on the right; copy a prompt back to the editor, or cold-read any stored session without resuming it (read-only).
- [**Themes**](docs/features/themes.md) — 20 built-in palettes (10 light + 10 dark) plus user theme discovery (`~/.dsh/themes/`); hot-switchable, `auto` follows your terminal.
- [**Search, selection & images**](docs/features/search-selection-images.md) — `Ctrl+Shift+F` over the whole transcript, drag-select copies to the OS clipboard, attachments from web/Feishu render inline, LaTeX replies draw as Unicode math.
- [**Slash commands**](docs/features/slash-commands.md) — `/model`, `/resume`, `/btw`, … plus everything dsh-native.
- [**Startup plugin tree**](docs/features/startup-tree.md) — every profile plugin with its installed npm version, printed at launch.

---

## Install and launch

```sh
dsh plugin --profile tui add @aiwayds/dsh-tui-pi
dsh --profile tui          # launch (or: dsh-tui-pi)
```

Legacy `session_projcache` records (missing `identity.isSeeded`/`identity.inheritedEventCount`, written before dsh 0.1.2-alpha.4 — predating the rc/stable floor of 0.1.5-rc.2 this plugin now targets) are migrated at the profile layer: the bundle patch replaces the stock `session-projection-cache` row with a wrapper (`@aiwayds/dsh-tui-pi/projcache`) that backfills the records while its module loads — strictly before the stock plugin could open the domain and crash the boot — so every `dsh --profile tui` start is covered, launcher or not. Migration is idempotent, backs up every rewritten file next to the original, and never blocks startup. The `dsh-tui-pi` launcher additionally runs the same migration as a CLI preflight before `exec dsh`.

Everything that used to need manual patching — the canvas background, the `@deepseek-ai` module closure, the compaction backend — now happens automatically. Upgrade an existing profile after a release:

```sh
node scripts/dev-upgrade.mjs                  # latest
node scripts/dev-upgrade.mjs 1.0.5 --dry-run  # preview the plan first
```

---

## Uninstall

```sh
dsh plugin --profile <name> remove @aiwayds/dsh-tui-pi
```

The `dsh-tui-pi` bin shim is global and can stay; if you installed the package globally and want it gone too: `npm -g rm @aiwayds/dsh-tui-pi`.

The host cleans up the profile automatically: the `dsh.profile.bundles` entry is spliced and the whole patch layer goes away with the package — the stock `session-projection-cache` row re-enables, and the projcache wrapper, the `tool-ask-user` insert and its disable row all vanish.

What stays on disk on purpose (deleting user data is destructive; a reinstall reuses all of it):

- `~/.dsh/APPEND_SYSTEM.md` — auto-seeded system-prompt appendix (plugin-owned; delete by hand if unwanted)
- `~/.dsh/tui-command-usage.json` — slash-command usage ranking
- `~/.dsh/model-profiles.json` — model profiles (SHARED: read by dsh-subagent-registry and dsh-profile-switch; per-agent edits via /agents write it)
- `~/.dsh/keybindings.json` — the dsh-tui app-key rows (host-shared file)
- `~/.dsh/agents/*.md` and `~/.dsh/skills/` — user-editable agents/skills (shared with other plugins)
- `.dsh-profile` pin files in project workspaces (written by /model profile pinning)
- the `dsh-tui:` section of `~/.dsh/settings.yaml` — theme/panel/footer/retention/subagent limits
- `~/.dsh/storages/session_projcache/` — the session projection cache, incl. `.bak-preflight-*` migration backups

While the plugin runs, the retention janitor (default `maxCount: 100` / `maxAgeDays: 30`, configurable in the `dsh-tui` settings) deletes old session logs — uninstalling stops that, but already-deleted logs are gone.

`scripts/install-font.mjs` mutates OS font/terminal state and has a documented backup; uninstall doesn't touch it.

---

## Companion plugins

**Default dependencies** — the nine plugins below ship with this package (installed into the profile's `node_modules`); activation still follows the profile's `bundles` list — list each one there to activate it.

- [@aiwayds/dsh-ask-router](https://www.npmjs.com/package/@aiwayds/dsh-ask-router) — fans every `ask_user_question` out to all answering surfaces (TUI panel, Feishu card); the first answer wins — list it in `bundles` before the UI bundles to activate.
- [@aiwayds/dsh-dcp](https://github.com/fan56/dsh-dcp) — the deterministic zero-LLM compaction backend.
- [@aiwayds/dsh-llm-proxy](https://github.com/fan56/dsh-llm-proxy) — SYSTEM proxy + per-host LLM outbound routing.
- [@aiwayds/dsh-llm-stats](https://github.com/fan56/dsh-llm-stats) — the `/llm-stats` usage ledger.
- [@aiwayds/dsh-mcp-adapter](https://github.com/fan56/dsh-mcp-adapter) — folds MCP tool schemas out of every prompt and adds the `/mcp` command ([demo](docs/features/mcp-adapter.md)).
- [@aiwayds/dsh-model-sync](https://github.com/fan56/dsh-model-sync) — syncs provider routes with the pi.dev model catalog.
- [@aiwayds/dsh-profile-switch](https://github.com/fan56/dsh-profile-switch) — `/profile-switch` + `/profile-cfg`: named model profiles switched and configured through the host's ask-user flow, on the TUI and the web (the panels this suite used to carry). Add it to your profile's `bundles` to activate.
- [@aiwayds/dsh-subagent-registry](https://github.com/fan56/dsh-subagent-registry) — registers `~/.dsh/agents/*.md` as `use_agent` subagents.
- [@aiwayds/dsh-web-search-anysearch](https://github.com/fan56/dsh-web-search-anysearch) — the AnySearch web search provider.

**Recommended install** — [@aiwayds/dsh-topics-memory](https://github.com/fan56/dsh-topics-memory), OKF topic memory for dsh (zero-LLM hot-path injection + a local git-tracked bundle; formerly dsh-llmwiki-memory):

```sh
dsh plugin --profile tui add @aiwayds/dsh-topics-memory
```

**Optional** — [@aiwayds/dsh-feishu](https://github.com/fan56/dsh-feishu) — drives the same dsh session from Feishu/Lark on your phone ([demo](docs/features/feishu-demo.md)).

---

## Keyboard shortcuts

| Key | Action |
|---|---|
| `Enter` | Send the prompt |
| `Esc` | **Double-press to stop everything** — the first press arms, the second opens a confirmation dialog naming what is running (main turn + subagent count); `Enter` there stops the main turn AND every running subagent, `Esc` keeps everything running. A popup open closes it instead. Works while only background subagents run. |
| `Ctrl+C` | Mid-task: first press stops (same everything-stop, no dialog), second quits; idle: clears editor / quits. Held-key auto-repeat never quits. |
| `Ctrl+D` | Quit (only when the editor is empty) |
| `Ctrl+L` | Open the model/think picker |
| `Ctrl+G` | Open the subagent picker (viewer `Enter` opens steer, `x ×2` stops that subagent while it runs / closes when settled) |
| `Ctrl+O` | Pending-message queue (s steer now · d remove) |
| `Ctrl+Shift+F` | Transcript search (`Enter`/`Ctrl+G` next · `Shift+Enter`/`Ctrl+Shift+G` previous · `Esc` close) |
| `↑` / `↓` | Browse submitted-message history |

Remap any app key through `~/.dsh/keybindings.json` (a partial JSON map, live-applied) or interactively with `/hotkeys`.

---

## Configuration

Every knob lives under the `dsh-tui` settings namespace in `~/.dsh/settings.yaml` (note the section name: `dsh-tui`). Theme / panel height / footer hints / icon set are `applies: 'live'` — a committed change hot-applies to the running TUI, no restart:

| Key | Default | Meaning |
|---|---|---|
| `theme` | `auto` | Color scheme: `auto` (follow the terminal) / `light` / `dark` / any registered theme name (`/theme` writes back to the same key) |
| `panelHeight` | `'1'` | Think/tool panel height: `'1'` / `'5'` / `'7'` / `'10'` / `'all'` (full content) |
| `maxAgents` | `4` | Max concurrently running subagents, `0` = unlimited (hot-tunable in `/agents → l` limits) |
| `maxRounds` | `75` | Max assistant messages per subagent before a wrap-up request is injected; `0` = unlimited |
| `maxRoundsGrace` | `7` | Grace rounds after the wrap-up before the child is force-stopped (session preserved, resumable); `0` = warn only |
| `disableSubagent` | `true` | Disable the native `subagent` tool; delegation goes through registered agents (`~/.dsh/agents/*.md`); `subagent_fork`/`workflow`/`ralph` stay available |
| `footerHints` | all `true` | Per-segment footer hint toggles: `send`/`stop`/`quit`/`quitEmpty`/`subagents`/`search`/`history` |
| `cacheHitMode` | `lastMessage` | Footer CH segment scope: `lastMessage` — the latest assistant message's cache-hit rate, matching the pi-tui footer (default); `session` — cumulative over the whole session |
| `iconSet` | `auto` | `auto`/`nerdfont`/`plain` — powerline glyphs adapt to your font; install a Nerd Font with `node scripts/install-font.mjs` |
| `rememberPreset` | `true` | Remember the last `/preset` selection **per workspace** (keyed by directory) and start the next launch there — the first session composes under it instead of the server-side default. `false` always starts on the server default. The memory itself lives in `$DSH_HOME/workspace-presets.json` |
| `favoriteModels` | `[]` | Favorite models (`provider/id`), pinned to the top of the `/model` picker |
| `hiddenModels` | `[]` | Hidden models (`provider/id`), moved to the picker's Hidden section (`f` favorites / `h` hides inside the picker — both persist to these keys) |

Session-store knobs (env overrides `DSH_TUI_RETENTION_*` / `DSH_TUI_RESUME_*`; precedence: settings.yaml > env > default):

```yaml
dsh-tui:
  retention:        # startup janitor for ~/.dsh/sessions — DELETES old logs. Once per startup.
    maxCount: 100   # <= 0 disables the janitor
    maxAgeDays: 30
    minIdleHours: 24
  resume:           # /resume display filter — only HIDES picker rows, never deletes.
    maxAgeDays: 30
    minBytes: 1024
```

Key remaps live in `~/.dsh/keybindings.json` (keyboard section above); `DSH_TUI_COPY_ON_SELECT=0` keeps drag-selection visual-only.

The plugin ships a bundled skill (`dsh-tui-pi-config`): ask the agent to "configure the TUI" and the guide loads automatically — it collects your choices interactively via ask_user_question (theme, panel height, subagent concurrency) and writes the `dsh-tui:` section for you. The full key table and the `DSH_TUI_*` env var list live in `skills/dsh-tui-pi-config/SKILL.md`.

---

## Development

```sh
pnpm check    # tsc --noEmit
pnpm build    # emit lib/
pnpm test     # unit tests, node --test against lib/ (pretest builds; 1,100+ tests across 60+ files — the current baseline lives in AGENTS.md)
```

`pi-tui` runs pristine from npm — no patches, no fork. See [AGENTS.md](AGENTS.md) for the iron rules and quality gates.

---

## Documentation

- [docs/features/](docs/features/) — one doc per feature, with demo videos.
- [ARCHITECTURE.md](ARCHITECTURE.md) — full design: process model, layers, data flow.
- [CHANGELOG.md](CHANGELOG.md) — release history.
- [AGENTS.md](AGENTS.md) — working conventions and quality gates for contributors.
- [docs/](docs/) — design notes (steer/follow-up flow, showcase drafts, …).

---

## Credits

The [Ask User Question](docs/features/ask-user-question.md) interaction is inspired by [juicesharp/rpiv-ask-user-question](https://github.com/juicesharp/rpiv-ask-user-question) (adapted to this TUI's docked-panel and dsh `userQuestions` provider architecture; all code here is original).

dsh-tui-pi

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README