Module: terminal
Embedded terminals for working on a machine from inside the app.
Status: implemented. The terminal.instance panel (xterm.js)
binds to a backend PTY session over the terminal channel — input/resize up,
output down — and kills its PTY on close, not on unmount. That distinction is
the whole reason a shell now survives a workspace switch: panes unmount whenever
their tab is not active and whenever you look at another workspace, and killing the
PTY there destroyed your cwd and anything running in it. The terminal lives in a
paneSession (see windowing),
and its xterm element is kept and re-attached so scrollback returns intact. A
consequence worth knowing: initialCommand is now typed once per pane, where it
used to be retyped on every return. runCommand opens a terminal
pre-running a command (via an initialCommand pane param). The agent's gated
terminal.exec tool is implemented and gated.
Which shell is a choice, not a fixed platform default — see Choosing a shell. On Windows that is what makes real bash available out of the box when Git for Windows is installed.
Contributions to the layout shell
- Panels:
terminal.instance(one PTY per instance, each in a window). - Commands:
terminal.new,terminal.kill(active),terminal.clear(active),terminal.focusNext/focusPrev(cycle, via thelayoutController.focusPaneseam). - Keybindings:
mod+k→terminal.clear, scoped toterminal.instance: it clears the focused terminal (the iTerm/VS Code convention) while shadowing the global command-palette shortcut, which still works everywhere else. See keybindings. (Declared asscope: 'terminal.instance', which normalizes towhen: "paneFocus == 'terminal.instance'".) - Services for other modules:
runCommand(cmd, opts)(exported asrunTerminalCommand) lets modules (e.g. agent chat showing a suggested command) open a terminal pre-running a command — always visibly, never hidden execution. - Settings:
terminal.fontFamily(enum of common monospace fonts; falls back to the system monospace if the chosen font isn't installed) andterminal.fontSize(px). Read live viauseSettinginTerminalPane; changes apply to open terminals immediately (xterm re-fits and the PTY is resized).terminal.shellis the standing default shell id (blank = the platform default); the pane's shell button is the discoverable way to set it. - Pane params:
cwd,initialCommand, andshell— soopenTerminal({ cwd, shell })opens a specific shell in a specific directory. A pane param beats the setting: it is a specific request, the setting is a preference.
Backend surface
backend/modules/terminal/ owns the PTYs — backend implemented. A
TerminalManager lives per /ws connection and routes the shared socket's
terminal channel; the frontend (xterm.js) will render it. The PTY always runs
where the backend runs — there is no client-side shell in either layout, so
browser and desktop are byte-for-byte identical and agents and humans share the
same terminals. Cross-platform PTYs unify on ptyprocess (POSIX) and pywinpty
(Windows ConPTY), which expose the same PtyProcess.spawn API behind
pty.py; the default shell is PowerShell on Windows (terminal.shell and the
pane's picker override it — see below). On POSIX it prefers
$SHELL, but that is often unset when the app is launched from a GUI launcher
rather than a terminal (and /bin/bash doesn't exist on every distro, e.g.
NixOS), so it falls back through common shells down to /bin/sh. Each PTY's
blocking read runs in a thread so it never stalls the event loop; sessions are
killed when the socket closes (resume-on-reconnect is a later enhancement). PTY
spawn/IO failures are sent to the pane as an error event and shown inline
([terminal error] …) rather than leaving a blank, dead terminal.
Channel protocol ({channel:'terminal', event, data}):
| Direction | event | data |
|---|---|---|
| client→server | start | {id, cols, rows, cwd?, shell?} |
| client→server | input / resize / kill | {id, …} |
| server→client | started | {id, shell, requestedShell?} |
| server→client | output / exit / error | {id, …} |
started echoes the shell that actually started, and carries requestedShell
only when that differs from what was asked for. A silent fallback would leave
the pane captioned with a shell it is not running, so the pane also prints the
substitution into the terminal itself.
Choosing a shell
GET /api/terminal/shells returns what this machine can launch —
{shells: [{id, label, kind, path, note}], default} — discovered by
backend/modules/terminal/shells.py and cached process-wide.
POST /api/terminal/shells/refresh re-probes, for a shell installed mid-session.
On Windows that is Git Bash, MSYS2 bash, PowerShell 7, Windows PowerShell, the
Command Prompt, and one entry per installed WSL distribution. On POSIX it is
$SHELL plus whichever of bash/zsh/fish/sh are on PATH.
Four rules are load-bearing:
The wire carries an id, never a path. shells.resolve() matches an id against
the discovered set and falls back to the platform default for anything else.
Anything that can open the websocket can send a start frame; if that frame could
name an executable, the terminal channel would be an arbitrary-exec route with a
PTY attached. This is the security boundary, and it is why path in the catalog is
display-only.
Git Bash is found by absolute path, never through PATH. On Windows
shutil.which("bash") resolves to C:\Windows\System32\bash.exe — the WSL
launcher shim, not Git Bash. Offering that under a bash label would hand the user
a shell whose filesystem is /mnt/c/..., where every cwd the app passes is wrong
and every path it prints is unusable by the file explorer beside it. Nothing errors;
the shell just quietly means somewhere else. WSL is offered, but only under its own
name with that difference stated. backend/tests/test_terminal.py pins this.
Three states, not two — the hardware module's rule. "WSL is
installed but would not answer" is a different fact from "there is no WSL", so such
an entry appears in the catalog with a note and no path, and the picker shows it
as unlaunchable rather than omitting it.
A shell runs the user-code Python, not the backend's. The backend lives in its
own venv (uv run puts <repo>/.venv first on PATH and sets VIRTUAL_ENV), and a
shell used to inherit it — so python script.py, which is how the agent runs code
through terminal.exec, got an interpreter with no torch, and a pip install there
modified the app itself. backend/modules/terminal/env.py removes the backend venv
from the shell's PATH and puts the notebook's interpreter first (the
managed venv carrying the AI stack, or the notebook.python override), setting
VIRTUAL_ENV when it is a venv. It never bootstraps one: until a notebook has been
opened, python is whatever the machine has.
Switching a pane's shell is a respawn: a PTY is bound to the process it started, so the old session is killed and a new one created. The picker says so before you choose.
Agent integration
Status: implemented (D3). Declared on the terminal.instance panel. Verified
live: the agent ran a command through gated terminal.exec, which prompted with
the rendered {command} shell specifier and ran it in a visible terminal on
approval. The terminal exposes
agent tools & getAgentContext, and is the most
security-sensitive tool surface in the app:
- Read (ungated):
terminal.list()andterminal.read(id)(recent scrollback); the active terminal's cwd viagetAgentContext(). - Gated:
terminal.exec(id?, command). There is no separate "authority" switch — what the agent may run is purely a function of the permission mode and rules: inplan/defaultthe command is prefilled and prompts before running; inautonomousit runs (subject todeny/askrules and therm -rf /circuit breaker). Execution is always visible in a real terminal pane — never hidden.
terminal.exec answers with the command's result, not just "sent". It returns
{ok, id, output, stillRunning?}: the terminal's id (a new terminal used to answer
{opened: true} with no id, so the model guessed one, failed, listed, and only then
could read), plus the recent scrollback once the shell is back at a prompt — output
quiet for 700 ms and a prompt on the last line (prompt.ts; quiet alone would
return mid-script when a program sleeps between prints). It waits up to 12 s, inside
the backend's 30 s tool timeout; past that it returns stillRunning: true and the
agent follows up with terminal.read. An unknown id is an error that lists the real
ones rather than silently opening a new terminal.
A tool pane's params reach it. The terminal is role: 'tool', and openPane
routes tools to openToolInDock — which used to take no options at all. So
initialCommand and cwd were dropped before the pane existed, and with a terminal
already docked, runCommand just focused it. openToolInDock now takes openPane's
opts: params on a non-singleton tool open a new instance carrying them, while a
plain open (no params) still focuses the docked one.
The initial command waits for the shell. It used to be typed on a fixed 250 ms timer, which Windows PowerShell's startup outlasts; input typed before PSReadLine is up is discarded, so the command simply never ran and the agent reported success over a bare prompt. It is now typed once the shell's startup output has gone quiet (400 ms, capped at 8 s so a silent shell can't hang it).
Matching a shell command safely is the bulk of the permission engine's work. The
terminal's specifiers reuse Claude Code's Bash/PowerShell rule logic: * globs
with word boundaries (terminal.exec(npm run *)), compound-command splitting on
&& || ; | (a rule must match each subcommand), wrapper stripping (timeout,
nice, …), and a built-in read-only allowlist (ls, cat, pwd, …) that runs
without a prompt in every mode.
Browser vs desktop
| Concern | Browser | Desktop |
|---|---|---|
| Where the shell runs | on the backend host (local dev: your machine; remote backend: the server — make this visible in the panel title) | localhost backend = your machine |
| Shell defaults | backend host's default shell | same (PowerShell on Windows) |
| Copy/paste, scrollback, themes | identical (xterm.js) | identical |
| Keybinding capture | browser reserves some chords (e.g. Ctrl+W) — the shell keybinding service must not bind those for terminal focus | full capture available |
Security note: exposing the backend beyond localhost exposes shell execution on that host. Any future remote-access story must address auth at the backend boundary, not in this module.