Skip to main content

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 the layoutController.focusPane seam).
  • Keybindings: mod+k → terminal.clear, scoped to terminal.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 as scope: 'terminal.instance', which normalizes to when: "paneFocus == 'terminal.instance'".)
  • Services for other modules: runCommand(cmd, opts) (exported as runTerminalCommand) 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) and terminal.fontSize (px). Read live via useSetting in TerminalPane; changes apply to open terminals immediately (xterm re-fits and the PTY is resized). terminal.shell is 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, and shell — so openTerminal({ 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}):

Directioneventdata
client→serverstart{id, cols, rows, cwd?, shell?}
client→serverinput / resize / kill{id, …}
server→clientstarted{id, shell, requestedShell?}
server→clientoutput / 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() and terminal.read(id) (recent scrollback); the active terminal's cwd via getAgentContext().
  • 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: in plan/default the command is prefilled and prompts before running; in autonomous it runs (subject to deny/ask rules and the rm -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​

ConcernBrowserDesktop
Where the shell runson the backend host (local dev: your machine; remote backend: the server — make this visible in the panel title)localhost backend = your machine
Shell defaultsbackend host's default shellsame (PowerShell on Windows)
Copy/paste, scrollback, themesidentical (xterm.js)identical
Keybinding capturebrowser reserves some chords (e.g. Ctrl+W) — the shell keybinding service must not bind those for terminal focusfull 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.