riesbri / dsh-tui

[!WARNING] This is alpha software, version 0.1.0. It works, it is tested, and it is used daily by its author — but it is young. Expect rough edges, expect features to be missing, and expect small breaking changes before 1.0. Two things to know before you point it at code you care about:

1. Tool calls are not reviewed before they run. In a standard setup, the agent can edit files and run shell commands inside your working folder without asking you first. That is how the harness is configured by default, not a choice this interface makes. How to change that →
2. Three other terminal interfaces for the harness exist, and one of them has more features than this one. An honest comparison →

Contents

• What it looks like
• Getting started
• Keys and commands
• How it works
• Why choose this one
• Documentation
• Security
• Contributing

What it looks like

╭──────────────────────────────────────────────────────────────────╮
│ dsh-tui 0.1.0                                                    │
│ ~/code/my-project                                                │
│ deepseek-official / deepseek-v4-flash                            │
╰──────────────────────────────────────────────────────────────────╯

───────────────────────────────────────────────────────────────────
› Read the LICENSE file and name the license. Use the read tool.

⏺ read file_path=~/code/my-project/LICENSE
  ⎿ <path>~/code/my-project/LICENSE</path>
    <type>file</type>
    1: MIT License
    … 21 more lines

● The LICENSE file is the MIT License.

╭─ my-project ─────────────────────────────────────────────────────╮
│ › ask anything                                                   │
╰──────────────────────────────────────────────────────────────────╯
  ● ready · deepseek-v4-flash · 14k/1.0M · /model · ctrl-d quit

Questions from the agent, approval requests, and the model picker all use the same framed box. While the agent is working, the status line shows a spinner, how long it has been running, and how full the context window is:

╭─ Indentation: Do you prefer tabs or spaces? ─────────────────────╮
│ ❯ Tabs                                                           │
│   Indent with tab characters.                                    │
│   Spaces                                                         │
╰──────────────────────────────────────────────────────────────────╯
  ↑↓ move · enter confirm · esc cancel

  ⠙ working 4s · deepseek-v4-flash · 13k/1.0M · ctrl-c interrupt

Getting started

You need two things: Node.js ^22.19 || >=24, and a working DeepSeek Harness installation with a model configured. If dsh web starts and answers a prompt, you are ready.

dsh plugin --profile tui add @riesbri/dsh-tui
dsh --profile tui

The first command creates a harness profile named tui and installs this interface into it. A profile is a named set of plugins; yours is now the harness's standard set plus this one. The second command starts a session in your current folder.

npm install -g @deepseek-ai/dsh

pnpm dsh plugin --profile tui add ~/path/to/dsh-tui/packages/tui

git clone https://github.com/riesbri/dsh-tui && cd dsh-tui
pnpm install && pnpm build
dsh plugin --profile tui add ./packages/tui

If you are an AI agent installing this, the install page is written to be followed step by step:

curl -s https://raw.githubusercontent.com/riesbri/dsh-tui/main/docs/install.md

If you are changing this repository rather than using it, start at AGENTS.md.

Keys and commands

Type / to see the commands your agent actually has. /model and /exit are handled by this interface. /compact, /plan, /goal, /permission and /feedback come from the harness, so which ones appear depends on your setup. Every command prints its result. A name that matches nothing is reported as unknown instead of being sent to the model as a question.

dsh --profile tui -C ~/code/api      # open a different folder
dsh --profile tui "run the tests"    # send a first message on startup
dsh --profile tui --resume           # reopen one of your recent sessions

Text-editing keys, the shift-enter caveat, a warning about /goal, and the permission presets are all in docs/usage.md.

How it works

There are two packages. @riesbri/dsh-tui-renderer does the drawing: character widths, keyboard decoding, the input line, boxes, and the screen. It knows nothing about agents. @riesbri/dsh-tui is the plugin: the session loop, turning session events into transcript lines, and the registry that other views can add themselves to.

• It never switches to a separate screen. Finished output goes into your terminal's own scroll history and is never redrawn. Only a small area at the bottom is updated in place. Scrolling, selecting text, and copying work exactly as they do for any other command.
• A reply is printed line by line as it arrives, so drawing cost does not grow with the length of the answer, and a long reply scrolls normally instead of being cut down to fit.
• Tool output is drawn the way each tool asks to be drawn. A shell command becomes a framed box with its exit code. A file edit becomes a red-and-green diff. A search groups its matches under each file. Tools that say nothing about presentation still display correctly.
• Model reasoning is shown while it happens, dimmed, so a model that thinks for a long time looks busy rather than stuck.
• Text from a model, a tool, or a paste is made safe before it is drawn. A terminal treats some characters as commands, so untrusted text is converted to a visible form first, and colors are added only afterwards.
• Character widths follow the Unicode standard for East Asian text, because one mismeasured character shifts every following row.
• Keyboard input is decoded in both formats terminals use, so a shortcut cannot work in one terminal and be dead in another.
• The banner, input line, status line, and every box are separate plugins registered into ctx.tuiSlots, so you can add your own.

Each of those had an obvious alternative that turned out to be wrong. The reasons are written down in docs/design.md.

Why choose this one

@dsh-tui/dsh-tui has the most features of the four. If you want the richest terminal experience today, install that one. Choose this one for three specific reasons instead:

1. It adds no third-party packages to your setup, so installing it cannot pull in anything unexpected.
2. It never takes over the screen, so your scroll history, text selection, and copying keep working.
3. It can answer the agent's questions. That connection point accepts only one provider at a time, and the web interface claims it — so only an interface running inside the agent can offer it.

The full comparison, including the disadvantages: docs/comparison.md.

Documentation

Security

Handling untrusted text is the most important part of this project. Everything on screen came from a model, a tool, a file, or a paste — and a terminal treats certain byte sequences as commands rather than as text. Without care, a reply could move your cursor, repaint lines you already read, or on some terminals insert text into your input. So everything that reaches the screen is converted to a visible, harmless form first, and colors are applied only to text that is already safe.

The repository also protects itself: dependency and license checks on every pull request, a scan of the full history for leaked secrets, static analysis with CodeQL, a check on the workflow files themselves, and an OpenSSF Scorecard rating. Two install-time rules matter most for a package like this one. Nothing published in the last 24 hours is installed, and an install fails if a package's publishing evidence becomes weaker than in its previous version — a common sign of a stolen maintainer account.

Releases are built and published by GitHub Actions from a tag, never from a laptop, so every published file carries a signature linking it to the exact commit it was built from. You can run the same checks locally with pnpm run security. To report a vulnerability privately, see SECURITY.md.

Contributing

pnpm install
pnpm build && pnpm test      # the full suite; no terminal and no model needed

Nothing outside this repository is required. Bug reports are especially useful right now — this is alpha software and the author cannot test every terminal. Start with CONTRIBUTING.md, and read AGENTS.md before changing code.

License

MIT. Not affiliated with, or endorsed by, DeepSeek.