English · 简体中文
dshell — a terminal-first AI workbench
One session is one terminal timeline: you type in a real shell, and the AI keeps working on the same screen. Every command you run and every turn the AI takes land in one column, in the order they happened. No chat bubbles.

The screenshots show the Chinese interface. dshell follows dsh's own language setting (Settings → General → Language), so every dshell surface is available in English too.
dshell is a set of plugins for dsh (DeepSeek Harness). It does not modify dsh's source: it plugs into dsh's documented extension points, so dsh stays upgradeable with upstream.
Contents
- How it fits together
- What it is
- What's new since 0.1.15
- Getting started
- A tour of the screen
- Two modes:
$ shelland✦ agent - The AI has a terminal of its own
- Full-screen programs
- Input assists: Tab, ↑, →
- Cross-session collaboration: pipes and the buffer
- SSH device sessions
- Settings
- The status card
- Gesture cheat sheet
- Three examples
- Limits worth knowing
- Docs for developers
How it fits together
dshell is two layers: a view you look at, and a host that does the work. What you see is always a view of something else — which is why one column can hold your shell output and the AI's turns at once, and why a session can be pointing at another machine while the window stays here.
flowchart TB
subgraph WIN["The window — a browser, or the desktop app"]
UI["One column: your shell output and the AI's turns<br/>the input line, the sidebars"]
end
subgraph HOST["The host — one Node process"]
CORE["dsh's own core<br/>sessions, the agent, the tool registry"]
subgraph ROWS["dshell's plugin rows — eleven packages"]
VIEW["mode + terminal-bridge<br/>the view, and the PTYs behind it"]
PANE["files + ssh<br/>the file pane, and where a session runs"]
LINK["buffer<br/>pipes, and the buffer between them"]
end
ROOT["the data root<br/>where dshell keeps its own files"]
end
subgraph WORLD["Where the work happens"]
HERE["This machine<br/>a real shell, a real tree"]
THERE["A device<br/>a real shell, a real tree"]
end
UI <-->|"one websocket"| CORE
CORE ---|"plugged in at dsh's extension points"| ROWS
VIEW -->|"your shell, your files"| HERE
VIEW -->|"the same session, pointed elsewhere"| THERE
PANE --> HERE
PANE --> THERE
LINK -.->|"files by name, between sessions"| HERE
LINK -.-> THERE
VIEW --- ROOT
PANE --- ROOT
Three bands, top to bottom:
- The window is the browser or the desktop app. It draws one column — your shell's output and the AI's turns, in the order they happened — and it sends what you type. It holds no state of its own: everything on screen comes from the host over one websocket.
- The host is dsh's own Node process. dshell adds plugin rows to it and changes none of
dsh's source, so dsh stays upgradeable with upstream. Those rows are the eleven packages listed
at the bottom of this page, and the data root (
$DSH_HOME/dshell) is where they keep their own files. - Where the work happens is a world: this machine, or a device. A session's commands, files and visible terminal all run inside one world — the device row is the same session, pointed somewhere else, not a second one.
The seams are where the interesting behaviour lives, and each has its own section below: the two PTYs (the AI has a terminal of its own), the file pane and the device routing (SSH device sessions), and the pipes and the buffer (cross-session collaboration).
What it is
| What you get | Details |
|---|---|
| A full-bleed terminal | One main shell per session, running real commands — full screen, colours, cursor |
| One merged timeline | Shell output and AI work interleave by time; each AI turn is a collapsible task block |
| Two modes | $ shell makes Enter run a command, ✦ agent makes Enter send to the AI — the $ / ✦ glyph in the input line is the mode, click it to flip |
| The AI's own shell | The AI gets a separate PTY, so it never blocks your foreground program and never steals your terminal |
| Cross-session work | Sessions form pipes to delegate tasks to each other and share files by name (the buffer) — including across SSH devices |
| Device sessions | Open a session directly on a remote machine: commands, files and the visible terminal all run there |
| WSL2 devices | A WSL2 distribution on this Windows machine is a device row of its own — its own terminal, files and agent session, with no credential to enter |
| Context without retelling | Switching to ✦ agent automatically carries your last few commands and their output to the AI |
What's new since 0.1.15
0.1.17 is on npm as latest. It is the release that makes a terminal survive a session
switch, turns a WSL2 distribution into a device row, and carries the port forwards that connect
a local port to a service on the device.
Its predecessor 0.1.16 changed one thing that matters at install time on its own: dshell no
longer pins a single dsh version but names a window of them, so every 0.2.1 release —
0.2.1-rc.5, today's latest, included — installs without waiting for a dshell release.
| What changed | What you notice | |
|---|---|---|
| WSL2 distributions are devices | A WSL2 distribution on this Windows machine is detected and offered as a built-in device row of its own — open a terminal on it, browse its files, hand it to the AI | There is no credential to enter (the distribution is its own credential) and no port forward to ask for: WSL2 shares this machine's loopback, so its ports are already reachable here |
| The 管理台 | dsh's Settings gains a dshell section — one page that gathers the whole suite's settings | 设备与凭据, WSL 发行版 and 终端与数据 as three cards on one page, instead of a configure control per plugin row |
| A ConPTY repaint no longer blanks the terminal | On Windows, a program that repaints its whole screen after a resize — the ConPTY signature — left a blank wall above the prompt | The region renders the rows that carry ink and cuts the dead frame around them, so the row count and the bytes agree again |
| A session switch keeps its prompt | Switching to a session and back reset its readiness, so a live device session flashed the first-dial panel over a terminal that was about to work | That the session reached a prompt is remembered for the page's life and across a reload, and seeded while the rebind handshake runs |
| A session switch no longer redials | Coming back to a terminal reopened the carrier, and the client drew "connecting" over a shell that had never stopped running. Three layers were wrong: the bridge indexed its shells by Agent object identity (an object that changes instance across a resume, an HMR reload or a host restart), binding a session released the device's live helper connection, and the client treated a rebind as a connection |
Switching away and back is silent: the same scrollback, no connecting copy, no second dial — and a real outage still shows, because the retry state is now an explicit fact rather than inferred from a counter that a redial resets |
| Port forwards | One SSH connection can carry a forwarded port, so a local port reaches a service on the device — from the panel and from the model's own tools | You can open a port on the device without a second ssh -L |
dsh 0.2.2-rc.1 is supported |
Every dsh peer range dshell declares now names a window of dsh versions instead of a fixed list | The plugin installs on anything from 0.2.1-rc.2 through 0.2.2-rc.1 — the published 0.1.14 does not install there at all |
| A distribution can be hidden from the pickers | A WSL2 distribution you never open a shell in is one more row in every device picker; the 管理台's WSL card now carries a per-distribution hide switch | The row leaves the new-session and device pickers, and nothing else: it still answers, and a session already bound to it keeps running there |
Getting started
Two ways in: install the published plugins into a dsh you already have, or build from this checkout.
Install into dsh
Prerequisites: dsh 0.2.1-rc.5 — either the desktop app, or the CLI
(npm install -g @deepseek-ai/dsh@latest) — and Node >= 24.11.0 with pnpm 9.15.0 on PATH
(dsh plugin forwards to pnpm). On npm, latest is 0.2.1-rc.5 and next is 0.2.2-rc.1 —
and both sit inside the window dshell declares, so either installs.
Which dshell release you want depends on which dsh you have:
| dsh | dshell |
|---|---|
0.2.2-rc.1 and every 0.2.1 release, plus 0.2.0, 0.1.7, 0.1.6, 0.1.5 |
0.1.17 — latest |
0.2.1 before rc.2, i.e. 0.2.1-rc.3 |
0.1.16 — its window is <0.2.2-0, so it also installs on every 0.2.1 release |
0.2.1-rc.2 |
0.1.14 |
0.2.0-rc.2, 0.2.0-rc.1, 0.1.7-rc.2, 0.1.6-alpha.2, 0.1.5-rc.2 |
0.1.13 |
dsh checks every @deepseek-ai/dsh-* peer a plugin declares against its own version and skips the
whole bundle when one does not match, so a dshell release declares the dsh versions it supports.
0.1.16 was the release that made that a window rather than a pinned version — before it, every
dsh patch release locked users out until a matching dshell release shipped.
That declaration is a range, not a list of exact versions, so a dsh patch or release candidate on
a line dshell already runs on installs without waiting for a dshell release. The window is one
file, dsh-upstream.json (support.range), and every manifest carries it:
0.1.5-rc.2 || 0.1.6-alpha.2 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || >=0.2.1-rc.2 <0.2.3-0.
So 0.2.1-rc.3 — and every later 0.2.1 release — installs without waiting for a dshell
release, and 0.2.2-rc.1 installs too — verified against a live container. A dsh from
a newer minor line than that window is what allow-version is for — dsh plugin --profile <name> allow-version <package@version> --dsh-version <exact> --accept-risk, which records the grant in
the profile's compatibility.json.
# One package: the bundle is the patch layer, it depends on the other eleven dshell
# packages, and dshell-ssh carries the one dsh package a stock profile does not
# ship (`@deepseek-ai/dsh-ssh`, its SSH execution provider).
dsh plugin --profile web add -w @nexus-aethra/dshell-bundle@latest
dsh web
dsh prints a tokenized URL (for example http://127.0.0.1:3080/?token=…). Open it in a browser.
In the desktop app, the same install is available as a window: 设置 → 插件, and give it
@nexus-aethra/dshell-bundle@0.1.17 (it installs from npmjs and pins the version exactly).
Skipping step 2 is not fatal — dsh boots and reports the two rows as
did not activate, and the rest of dshell works. It is listed because the SSH device sessions and the agent's terminal tool both resolve those names from the profile.
The bundle carries every dshell package and its own cordis.patch.yml, so dsh composes the dshell
rows the moment the package is installed: no profile edit, no config file. dsh plugin --profile web list shows the resulting layer stack.
Build from this checkout
Prerequisites: the same Node and pnpm, plus an upstream dsh/ checkout next to this repository (it
is git-ignored here).
# 1) dsh upstream (once)
cd dsh
pnpm install --no-frozen-lockfile
pnpm run build:lib && pnpm run build:web
# 2) the dshell plugins
cd ..
pnpm install
pnpm --filter "@nexus-aethra/dshell-*" run build
# 3) install into dsh's web profile (once; re-running is safe)
./scripts/install-into-dsh-profile.sh
./scripts/bootstrap-profile-client.sh
# 4) every time
cd dsh && pnpm dsh web
Check either install with
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3080/ — it should answer 401,
which is dsh's cookie auth gate, not a failure.
The details and the troubleshooting (why the versions are pinned, how the profile gets filled in, the module-loader contract for client bundles) live in
docs/dshell-setup.md.
A tour of the screen
The left sidebar holds your sessions, the middle is the terminal timeline, the status card floats in the top right, and the input line sits at the bottom.
| Area | What you can do |
|---|---|
| Left sidebar | Create and switch sessions; 归档 files one away into the 已归档 group; 多选 then batches 恢复 / 删除; a deleted session first moves to 待删除 · 重启后清除 |
终端 section |
Its own section below the workspace list: the link glyph first in its header opens the cross-session pipe panel (provided by dshell-buffer, and it survives the fold, being the panel's only entry); + mints a terminal session; the pill at the row's end says where that shell runs (本机 or the device name); double-click the title, or use the row's ⋯, for 重命名 / 归档; the section header also carries the search and the archived filter |
| Right sidebar: files | The 文件 tab browses the session's working directory with back/forward; double-clicking a directory makes it the root; drag a directory onto the terminal to cd there; device sessions also get 打开文件传输 |
| Status card | Always in the top right, collapsed to one line; expand it for the AI terminal, subagents, background jobs, buffer transfers and delegation replies |
| Input line | the $ / ✦ glyph is the mode — click to flip, hover for its name; ? names the gestures that are live, on hover |
The timeline is the point: a stretch of shell output occupies one region (a real mini terminal that scrolls horizontally), and one AI turn occupies one task block. The block's header line says what it is doing, for how long, and what it has spent; clicking it folds the block into a two-line summary.

Two modes: $ shell and ✦ agent
The $ / ✦ glyph at the left of the input line is the mode — click it to flip, hover it to read
which one it is. The same switch is a slash command typed right in the input box:
| Input | Effect |
|---|---|
/shell <command> |
Switch to shell mode and run the command immediately (/terminal is an alias) |
/agent <text> |
Switch to agent mode and send the text to the AI |
/fullscreen |
Hand the whole surface to the program on the terminal (the way in when the reading misses) |
/new |
Create a session that inherits the current session's working directory |
In $ shell mode:
Enterruns the line, into the foreground process of the main shellCtrl+Cabandons the line and interrupts the terminalCtrl+Shift+Vhands the clipboard to the terminal- Anything starting with
/still goes down dsh's command channel (/compactand friends are untouched)
In ✦ agent mode Enter simply sends. Switching to agent mode also attaches your last three
commands and their output (2 KiB each, with the agent able to page further on demand), so you never
have to explain "that command I just ran failed".
flowchart TB
IN["The input line — one keypress either way"] --> S["$ shell<br/>Enter runs the line in this session's shell<br/>Ctrl+C abandons it"]
IN --> A["✦ agent<br/>Enter sends the line to the AI<br/>your last three commands come along"]
S -->|"click the glyph, or /agent"| A
A -->|"click the glyph, or /shell"| S
The AI has a terminal of its own
Every session has two shells:
- Your main shell — you type, you see it, rendered full width.
- The AI's shell — spawned lazily on first need, starting in the directory your shell is in.
Neither can take the other's foreground. The AI cannot type into your terminal; it can only read it
(dshell_terminal_read). To watch what it does in its own shell, expand the status card's AI 终端
row: a read-only live view, with 为 AI 开启一个终端 whenever it is not running.
If dsh's bash tool spawns a persistent shell in the same session, dshell claims it as the AI's
terminal, so the model's bash calls, terminal_send, and the panel you are watching all converge on
one PTY — no more "the panel shows one shell while the model ran its command in another".
flowchart LR
YOU["Your main shell<br/>the foreground, full width"] -.->|"the AI may only READ it<br/>(dshell_terminal_read)"| AI["The AI's own PTY<br/>spawned on first need"]
AI -->|"its own commands"| OUT["Its own output<br/>in the status card"]
Full-screen programs
A program that takes the whole screen — vim, htop, less, a coding TUI such as minimax-code —
gets the surface instead of the timeline. The composer steps aside, the terminal fills the column, and
every key goes straight to the program: the arrows, Tab, Escape, the control chords, and the mouse
reporting it asks for. This is the one case where the composer is not the input line, because a
program that reads the keyboard itself cannot share it with a line editor.
dshell decides this on its own, from two readings of the session's terminal: a foreground program that
is painting the screen (hiding the cursor, opening a synchronized update, enabling mouse reporting),
or the alternate screen that vim and friends switch to. Either one is enough. A long command is not
a full-screen program — npm install and sleep 30 keep their timeline.
flowchart TB
T["The timeline"] -->|"a program takes the surface<br/>(vim, htop, less, a TUI)"| F["The program's own screen<br/>every key goes straight to it"]
F -->|"it exits, or 退出全屏"| T
F -.->|"its repaints are kept OUT of the timeline"| L["the session's raw log"]
| Getting out | the 退出全屏 button on the small bar over the program's own screen — or just quit the program, and the timeline comes back by itself |
| Getting in by hand | /fullscreen, for a program the reading misses |
| While it is on | the transcript is not rendered at all, and the program's output is kept out of the timeline on purpose: its repaints would land there as a wall of half-drawn screens. It is still in the session's raw log, so a reconnect replays the screen |
| A device session | only the alternate screen is read there (the local process is ssh), so the button is the way in for everything else |
Input assists: Tab, ↑, →
All three live in the $ shell input line and each can be switched off independently.
flowchart TB
W["the word under the caret"] --> P{"what the line says that word is"}
P -->|"the command position<br/>(also after sudo, or after ;)"| C["command names<br/>from the session's own PATH"]
P -->|"right after cd"| D["directories"]
P -->|"anywhere else"| F["paths"]
C --> R["one candidate lands directly<br/>several open a floating list"]
D --> R
F --> R
| Gesture | Behaviour |
|---|---|
Tab |
Completes the word under the caret, from what the line says that word is: a command name in the command position (dock + Tab, and equally sudo dock + Tab or pwd; host + Tab), a directory after cd, a path anywhere else (a redirection's target included) — and the subcommands and options the session's own shell knows, so docker r + Tab offers rename/rm/run and apt list -- + Tab offers the long options. Names come from the session's own world — this machine's PATH for a local session, the device's for an SSH session — so the two answer with different names. The comparison folds ASCII case, but the completion carries the real spelling: cd nexus-sh + Tab becomes Nexus-shell/, correcting the line as it completes. A single candidate lands directly; several open a floating list (Tab/↑/↓ to move, Enter to take, Esc to close) |
↑ |
Opens this session's history (↑↓ to move, Enter to take), listing only commands that share a prefix with what you have typed |
→ |
Shows a ghost hint after the caret: the newest command that exactly extends your draft. Each → takes one word of it, and the ghost disappears with the last word |
The ? in the input line shows the same legend for the current state — → 采纳一个词 · 继续 while a
ghost is showing, Tab 下一个 · ↑↓ 选择 · Enter 填入 · Esc 关闭 while a list is open — and names the
mode in force. Hover it (or focus it with the keyboard) to read it. Turn an assist off and its key
reverts to the browser's behaviour (Tab moves focus, → moves the caret).
Cross-session collaboration: pipes and the buffer
This is what separates dshell from other terminal workbenches: sessions are not islands.
Two sessions can be joined by a pipe, after which their AIs can delegate tasks to each other and share files. A pipe can span machines — either end may be a session bound to an SSH device.
flowchart LR
A["Session A · this machine<br/>the window you type in"] -->|"pipe: deploy"| B["Session B · build host<br/>an SSH device session"]
A -->|"pipe: review"| C["Session C<br/>another local directory"]
B -->|"the result"| A
C -->|"the result"| A
Creating a pipe (only you can)
Click the link glyph at the left of the 终端 section's header (it survives the fold, being the
panel's only entry). The panel has two views:
列表—+ 建立管道, pick two sessions, give it a name (such as "build host") and a purpose — one line saying what travels over this pipe and why — then建立管道.图— sessions are nodes and pipes are edges. Drag from a node's dot onto another node to create one; click an edge to see its detail or解除.
A pipe joins terminal sessions — the ones the sidebar's 终端 section lists. A plain conversation
is not offered as an endpoint, and the host refuses one: the file pane, the device routing and the
section all key off the terminal identity, so a session that is not a terminal could not serve a
request anyway.
The purpose is the part the other side reads: it travels in the peer's standing prompt next to that
pipe, so a peer's model can tell whether an incoming request belongs there. Either end can write it —
you from the panel, an agent with dshell_buffer action="describe" — and the panel says when the words
are the other session's rather than yours (由 … 填写).
The panel says 只有你能建立管道;agent 没有建连的工具 — connecting is always your move; an AI can only
use pipes that already exist.

What one delegation looks like
Delegation is asynchronous. A busy peer simply queues the request, and the requester does not block: its turn ends, and it is woken up again when the answer comes back.
sequenceDiagram
participant U as You
participant A as Session A (local)
participant B as Session B (build host)
U->>A: deploy this directory to the build host
A->>A: check that the pipe is live
A->>B: delegate the task, granting read on "src"
Note over A: this turn ends<br/>status card shows ⏸ waiting for B
B->>B: claim the ticket, read /src/… in its own world
B->>B: run the build
B-->>A: finish, report the result
Note over A: [pipe report] arrives<br/>A wakes up and continues
A-->>U: reports back to you
The peer sees only what you send it: not your other files, not your other sessions. Tickets have a
deadline; a watchdog settles an unanswered one as 已超时 and tells the requester, who can delegate
again or carry on alone.
flowchart LR
Q["queued"] --> P["in progress"] --> D["done"]
P --> F["failed"]
P --> T["timed out"]
Q --> X["cancelled"]
The buffer: handing files over by name
A delegation can open files or directories from your own world to the peer, each with a name and
read and/or write rights. That name becomes the peer's buffer path; the buffer is a tree rooted at
/, one per session:
flowchart LR
subgraph W["Session A: real disk"]
D1["/srv/app/README.md"]
D2["/srv/app/releases/"]
end
subgraph B["Session B: the buffer at /"]
P1["/readme"]
P2["/app/releases/v0.4.2.tar"]
end
D1 -->|"grant as=readme, read-only"| P1
D2 -->|"grant as=app, read+write"| P2
The holder of a grant works through five actions:
| Action | Effect |
|---|---|
ls |
With no path, lists every mapped area you hold (name, rights, who it came from); with a path, lists a directory |
read |
Reads a text file, paging by line |
edit |
Edits that file in place inside the granter's world — no copy is made |
download |
Copies a buffer file into your own world (at a destination you choose) |
upload |
Pushes a file from your world into the buffer |
Two rules are worth remembering:
- The mapping is the contract. Paths can only land under a name you were granted; absolute paths,
.., and symlink escapes are refused. The AI never needs to know your real paths, and cannot touch anything else. - The grant holder acts. To give someone a file, grant read and let them
downloadit. To receive one, have them grant write anduploadit yourself.
Grants are reference counted: settling a ticket revokes its grants, and a grant at zero is gone — nobody has to remember to clean up.
Big files
Above 32 MiB, download and upload switch to a chunked relay: 16 MiB slices moved one at a
time, then verified end to end by a whole-file sha256. A mismatch is a hard failure and keeps the
intermediate data (1 GiB by default, 4 GiB hard ceiling). Progress shows up live in the status card's
⇅ 缓冲区传输 row, with a percentage and a bar per transfer, even with the panel closed.
What the detail page shows
Clicking a pipe opens its detail page:

- 缓冲区 — a walkable tree with the same feel as the right sidebar's file browser (crumbs,
刷新, hover highlight); each row says where it came from and with which rights. - 进行中的请求 / 已结束 — every ticket's state, direction, subject and full reply.
- 生效中的授权 — the grants that are live right now, and the real path each one maps.
The screenshot above is a pipe after its task settled: the grants have already been reclaimed, so the buffer is empty again. That is by design.
SSH device sessions
In the 新会话 dialog, switch 运行位置 to SSH 设备, pick a device and a remote directory.
Creating the session proves the connection with a real ssh round trip first; if it fails, no session
is created.
Devices themselves are registered on the Plugins panel — 插件 in the sidebar →
@nexus-aethra/dshell-bundle → the dshell-ssh row's 配置 — with a name, host, port, user, remote
working directory, and either 密钥 (an OpenSSH private key) or 密码, both held in a vault group.
- Connections use an embedded SSH client (
ssh2), carrying only that device's own key — no hostsshbinary, no~/.ssh/config, no ssh agent; - Passwords are handed to that client directly, never onto a command line;
- Keys and passwords live in
$DSH_HOME/dshell/ssh/keys/, mode0600; - Host keys are trusted into dshell's own
known_hosts, leaving your personal file alone. A successful测试reports已连接 user@host(system)· N msand, when a host key is trusted,主机密钥 SHA256:…(首次信任,请与服务器管理员核对 | 已信任).
Not supported: hardware keys (sk-* / FIDO / PKCS#11), ~/.ssh/config directives such as
ProxyJump and ProxyCommand, and agent forwarding. A device behind a bastion needs the bastion
itself registered as the device.
Once bound to a device, that session's commands, files and terminal all live on the device:
flowchart LR
subgraph L["Your machine"]
S["the session's terminal UI"]
M["a mount stand-in directory<br/>mnt/device/remote-dir"]
end
subgraph R["The remote device"]
T["a real shell<br/>(your visible terminal)"]
F["the real file tree"]
end
S <-->|"ws /dshell/pty"| T
M -.->|"mirrored view"| F
The prompt in your terminal is the device's prompt — this session is root@VM-0-6-ubuntu, and
that is where its commands run:

Such sessions wear an SSH badge in the sidebar. Their right sidebar gains 打开文件传输: two
panes, 本机 and 设备, and dragging a file or folder from one to the other starts the copy — with
per-item progress, chunk counts, skip counts, and an 覆盖 / 移除 question when something already
exists. (32 MB per file, 20 000 entries or 2 GiB per plan.)
The 文件 tab of that sidebar browses the device's tree, not this machine's — the breadcrumb is
the device's own path:

A WSL2 distribution on this Windows machine shows up as a built-in device row of its own:
wsl.exe is asked what is installed, and every WSL2 distribution becomes a row you can pick as
a session's 运行位置 — its own terminal, its own file pane, its own agent session.
There is nothing to configure and nothing to enter: no credential (the distribution is its own
credential), no host key (there is no handshake to verify) and no helper to deploy. Nor is
there a port forward to ask for — WSL2 shares this machine's loopback, so its ports are already
reachable here, and dshell refuses the forward with that reason rather than opening a tunnel that
would bind a second socket to bytes the first one already carries. The rows are listed in the
管理台 (设置 → dshell) under WSL 发行版, with a 测试 that reports the distribution's own
system information.
Settings
dshell configures itself on dsh's Plugins panel, on the row each setting belongs to: open 插件
in the sidebar, pick @nexus-aethra/dshell-bundle, then use the 配置 control on a row.
| Row | Contents |
|---|---|
dshell-mode |
终端配色 — 午夜 (default), 柔和, 神秘, 森林, applied instantly; 输入辅助 — the Tab 补全, 历史列表, 智能提示, 子命令与选项 switches; 数据目录 — where dshell keeps its own files, moved at the next start |
dshell-ssh |
The device list, each row offering 测试 / 编辑 / 删除 |
One page holds all of it: dsh's Settings → dshell — the 管理台 — lists 设备与凭据,
WSL 发行版 and 终端与数据 as three cards side by side.
Settings are stored on the host and shared by every browser on it — turn an assist off here and it is off in the other browser too.
The status card
Pinned to the top right, collapsed to a single line until you expand it. Rows appear only when they have something to say:
| Row | When it shows |
|---|---|
计划 |
The AI has a todo list; progress and the current step |
AI 终端 |
The AI's shell is up; expand for the read-only live view |
智能体 |
Subagents are running; click one to open it |
后台任务 |
Long-running jobs |
缓冲区传输 |
Files are moving between worlds, with progress bars |
中断点 |
You handed this turn to someone else and are waiting (⏸ 等待 <peer> 回信); reversible with 撤回 |
管道任务 |
Another session delegated work to you; lists the pending tickets |
连接 |
The host websocket dropped; offers 重新连接 |
| On Windows the integrated terminal cannot run: it needs a POSIX shell and there is none on the host, so the terminal view says so and offers the way out — bind a device and the session's terminal runs on that machine instead. A device-bound session is unaffected, and needs nothing installed on Windows: the connection is dshell's own SSH client, not the operating system's. |
Opening the card heads it with the machine this session runs on: CPU and memory, each with a bar carrying the whole green→yellow→orange→red ramp and clipped to the share in use, so the colour at the bar's edge is the colour for that load. Below them are its cores, load average and exact memory. A session bound to a device reports the device's figures and names it, and an unreachable one says so rather than falling back to this machine. Nothing is shown until the session has taken its first input — until then the device is still yours to pick.

How often that is re-read is yours to choose, under 设置 → 插件 → dshell → 资源读数: 2s / 5s / 10s / 30s / 1m. On this machine a tick is one file read; on a device every tick is a round trip over ssh.
Gesture cheat sheet
| Where | Action | What it does |
|---|---|---|
| Input line | click $ / ✦ (or /shell, /agent) |
switch modes |
| Input line | hover ? |
the key legend for the current state |
| Input line | Tab |
completion: commands in the command position, directories after cd, paths elsewhere (case-insensitive match, real spelling applied) |
| Input line | ↑ |
command history list |
| Input line | → |
take one word of the ghost hint |
| Input line | Ctrl+C / Ctrl+Shift+V |
interrupt / paste into the terminal |
| Input line | /fullscreen |
hand the whole surface to a full-screen program |
| Terminal | drag a directory in | cd the terminal there |
| Timeline | click a task block's header | fold / unfold it |
| Timeline | the right-edge bookmark rail | jump to an AI turn |
| Sidebar | 管道 |
open the cross-session pipe panel |
| Sidebar | hover a row | 归档; archived rows also 恢复 / 删除 |
| Status card | click ▾ |
expand the details |
Three examples
1. Edit locally, build on a build host
- Register the build host in Settings;
新会话→运行位置: SSH 设备→ pick it → remote directory/srv/order-gateway. - Create a pipe from your local session to that one, labelled "build host".
- Tell the local session: "deploy this change to the build host and verify it." It delegates, the build-host session runs the work on its own machine, and the local session wakes up with the answer. Your terminal's foreground is never occupied.
2. Two sessions review each other (the screenshots above)
- Create two sessions,
demo(the code) anddemo-peer(the release notes), and pipe them together with the label "review". - In
demo, say: "delegate this to demo-peer — map my README.md asreadme(read-only), have it read the file and report a review." democonfirms the pipe, sendsdelegate(with a read-only grant namedreadme), and its turn ends.demo-peerwakes up, reads/readme, writes the review, andfinishes the ticket.demoreceives the[pipe report]and continues on its own. The pipe's detail page shows the ticket, the full reply, and the grant that was reclaimed once it settled.
This is exactly what produced the two screenshots above — the run is real, not staged.
3. Move a large file between machines
- One session on each end (local and device), joined by a pipe.
- Have whichever side holds the file
uploadit, or have the side that needs itdownloadit, to a path in the buffer (say/app/releases/v0.4.2.tar). - Anything above 32 MiB is chunked and sha256-verified automatically; the status card's
⇅ 缓冲区传输row tracks it, and both sides clean up their temporary slices when it is done.
Limits worth knowing
- A restart keeps the scrollback but not the PTY process. Restarting dsh spawns a fresh shell;
earlier output is restored from the on-disk log (
$DSH_HOME/dshell-pty/, files0600in a0700directory). - That transcript records what you type. Both output and input are captured, so anything typed at an interactive prompt — a password included — lands in the file. It stays on this machine with owner-only permissions, but treat it as recorded.
- A session's working directory is immutable. The terminal may
cdfreely; the session's own root is fixed. A different directory means/new. - Deleting a session takes two steps. After
删除it sits in待删除, and its log is cleared at the next dsh start;取消reverses it until then. - One browser connection per session. A second websocket binding to the same session is refused.
- Archived is not deleted. An archived session stays in the pipe graph (it can still be a valid endpoint); only deletion removes it.
- Browser and desktop control are local-session only. A device session — an SSH device or a WSL one — gets neither, on purpose: both would act on this machine while the session works on another. The install note above lists the two upstream packages that make the desktop half available at all.
- Full-screen mode reads the foreground on this machine only. A device session is detected by the
alternate screen alone, so a full-screen program that does not switch buffers needs
/fullscreenthere. The reading is Linux's:dsh webon macOS or Windows has the reading and nothing else. - WSL is WSL2 only. A WSL1 distribution is filtered out and never becomes a row: the transport is built on what WSL2 gives — a ConPTY pty and a loopback shared with this machine.
- A WSL distribution has to exist on the machine. The rows are derived from
wsl.exe, never stored: uninstall a distribution and its row is simply gone. Nothing about a WSL device is persisted, so there is nothing to clean up and nothing to restore. - A built-in row cannot be edited or deleted. A WSL row is the machine's own answer, not a saved device, so the registry refuses to save or remove it.
- A WSL device has no port forwards. WSL2 shares this machine's loopback, so its ports are already reachable here; dshell says so instead of opening a tunnel that would bind a second socket to bytes the first one already carries.
- The pipe panel refreshes by polling (about every 3 seconds) — there is no push channel. In-flight transfers refresh the status card once a second.
Docs for developers
| Doc | Read it when |
|---|---|
docs/dshell-design.md |
You want the goal, the non-goals and the design decisions (including why this is not a chat window) |
docs/dshell-architecture.md |
Before writing code: the ws protocol, the Cordis extension points, package layout, CSS conventions |
docs/dshell-packages.md |
You need to know which plugin owns a feature |
docs/dshell-roadmap.md |
The phase plan and each phase's acceptance check |
docs/dshell-setup.md |
Setting up a machine, troubleshooting, build order |
docs/README.md |
The documentation index and its update rules |
Eleven packages (@nexus-aethra/dshell-*), published together: std (contracts), storage (storage
engines), bundle (the single patch layer), conversation, terminal-bridge, mode, commands,
files, ssh, buffer and wsl (this machine's WSL2
distributions as built-in devices).
License
MIT, see LICENSE.
No comments yet. Be the first to write one.