Workspaces & terminals#

A workspace is a named project context that owns a set of panes. Most of those panes are real PTYs running a coding CLI — claude, codex, opencode, packetcode — or a plain shell; the rest are chat conversation tiles and file viewers. Workspaces persist across restarts, hydrate dormant, and only start processes once you actually open them.

The surface is reached from the left rail (terminal icon), from the command palette, or with Ctrl+Shift+W.

A workspace with several PTY panes tiled by the mosaic, the workspace tab strip above them and the Git panel docked at the right.

What a workspace holds#

Every workspace record carries these fields (src/types/workspace.ts):

Creating a workspace#

The + button on the tab strip (tooltip: "New workspace (choose template)…") opens the New Workspace dialog. The Fleet sidebar's own "New workspace" CTA is the instant path; this one is the templated fork.

Templates#

Picking a template pre-selects a set of CLI sessions and seeds the name. Any session the template names that is not installed is silently dropped from the selection.

Form fields#

• Name — auto-seeded from the template or the chosen folder; typing in it marks the name as hand-edited and later template clicks stop overwriting it.
• Location — Local or Remote. Remote asks for an SSH server and a remote project path, and probes that the path exists.
• Project folder — a recents dropdown plus a native folder picker. For a remote workspace you can instead clone a repo URL (with an optional branch; blank means the repo's default branch).
• Agent sessions — checkboxes over the five slots. Not-installed slots show an Install link (or, for PacketCode, a Set up button that jumps to Settings → CLI clients).
• Model / effort overrides — per slot. Claude Code seeds effort: medium.
• Bypass permissions — see the warning below.
• Prompt — "Describe the task for all CLI sessions…". This becomes workspace.prompt and is written into every non-terminal pane's stdin once its session is ready.

The workspace header#

A single 33px row across the top of the surface:

Bypass permissions#

The toggle sets workspace.bypassPermissions, which appends one flag at the next session launch:

Adding panes#

+ Add Session opens a 320px picker with a search box ("Search CLI sessions…"). It has three sections.

CLI sessions#

One row per terminal slot. PacketCode floats to the top with a Recommended pill when it is installed. A row that is not installed is disabled and grows an Install link (PacketCode gets a Set up button instead).

Install-hint links point at the Claude Code docs, the openai/codex repo and opencode.ai respectively. On an SSH workspace, "installed" means the server record lists that agent in installedAgents, not your local machine.

Two extra controls appear on rows that need them:

• Account chip — only on claude-code and codex, and only once you have registered a CLI account. Leaving it untouched keeps the one-click fast path (the sticky per-project default is resolved for you). Changing it makes that account the project's new sticky default.
• Shell select — only on the Terminal row. Defaults to "Default shell", meaning inherit. Unavailable profiles render as … · unavailable and are disabled.

The WSL row#

On Windows, when at least one distribution is detected, a separate WSL · <distro> row appears. It is exactly a Terminal pane carrying a wsl shell selection — no new pane kind, no second launch path.

Viewers#

• File Viewer — "Open any file as a tile". Opens a native file dialog rooted at the project path.
• Markdown Viewer — "Open a .md rendered". Same tile, filtered to .md/.mdx and opened in preview mode.

Both are disabled (not hidden) on SSH workspaces, with the tooltip "File viewers read the local filesystem — not available on SSH workspaces".

Re-opening a file that already has a tile focuses the existing tile rather than stacking a duplicate viewer.

Shells#

Terminal panes resolve their shell from three levels, most specific first:

1. pane.terminalShell — set when you picked a shell (or the WSL row) at add time
2. workspace.terminalShell — the workspace default
3. The app default, persisted in localStorage under packetbench:terminal-default-shell

Available profiles#

Windows offers auto, powershell7, windows-powershell, command-prompt, git-bash, wsl, custom; everything else offers auto, bash, zsh, custom. The custom row is hidden from the picker unless your app default is already a custom shell.

Custom shells are allowlisted#

A custom executable is only honoured when its program name (path and .exe/.cmd/.bat stripped, lowercased) is one of:

bash  cmd  fish  nu  powershell  pwsh  sh  wsl  xonsh  zsh

Arguments are parsed by PacketBench's own tokenizer, not by a shell: quotes group, a backslash escapes only whitespace / quotes / another backslash (so ordinary Windows path separators survive), and at most 32 arguments are kept.

The mosaic#

Panes are tiled with react-mosaic. The layout is built from a preset the first time and then grown by appending, never re-nesting:

New panes are appended to the root split so no surviving tile changes depth — re-nesting a leaf would remount it and kill its PTY.

• Drag a tile by its header bar to reorder.
• Drag a splitter to resize. The new tree is only persisted on release, and a tree carrying a collapsed (0%) split is refused — that shape only appears mid-drag.
• Zoom with the tile's maximize button or by double-clicking its header. Zoom is CSS-only: every other tile stays mounted and hidden, so no PTY is interrupted. Press Esc to exit — unless focus is inside the terminal, which owns every keystroke; then use the tile's zoom button. The on-screen hint says exactly this.

The pane header and overflow menu#

Each terminal tile's header is one row: drag grip, a pulsing status dot, the pane identity, an account chip (ambient panes show nothing), a status pill, a zoom button and a ⋮ overflow menu.

The status pill reads one of: not installed, approval, running, error, idle. Terminal panes label themselves Terminal · <shell label> — or Terminal · Remote login shell on an SSH workspace.

The overflow menu:

Model catalogues per slot#

Effort levels are Low / Medium / High and become --effort <level>.

How a terminal session actually starts#

1. The pane mounts and, if it is in the visible and selected workspace, arms a single automatic launch after a 200 ms delay. That launch happens once per pane — toggling visibility or changing memoised options never silently restarts a running CLI.
2. Concurrent starts for the same pane are deduped in a module-level registry. Without this, React StrictMode's double-mount spawned two PTYs; harmless for claude/codex, fatal for opencode (the second instance exits 1 and leaves a permanently blank pane).
3. The frontend calls create_pty_session with the project path, current terminal dimensions, the command, args and env.
4. The backend validates the command against the allowlist, resolves it to a real executable, opens a PTY and spawns the child.
5. Output streams back on pty:output:<sessionId>; exit arrives on pty:exit:<sessionId>. On attach the frontend replays the server-side transcript first, then any events it buffered while replaying, so nothing is lost or doubled.
6. If workspace.prompt is set and the pane is not a plain terminal, the prompt is written to stdin — immediately for claude, after a 3-second delay for everything else so the TUI has time to initialise.

The command allowlist#

create_pty_session refuses anything whose program name is not in:

claude  codex  opencode  packetcode
bash  sh  zsh  powershell  pwsh  cmd  wsl  fish  nu  xonsh
ssh

The check is on the program name — directory components and a trailing executable extension are stripped and the result is lowercased — so a pinned absolute path like D:\tools\packetcode.exe validates as packetcode.

The error is explicit: Command '<x>' is not allowed. Allowed commands: [...].

Working directory rules#

Environment applied to every PTY#

TERM=xterm-256color and COLORTERM=truecolor are always set, then your pane-supplied env is merged on top.

For claude panes specifically:

The status-line helper path and state directory are applied after your pane env, so persisted workspace state cannot redirect them.

Binary resolution#

On POSIX, resolution is: an app pin at ~/.packetbench/<command>-bin containing an absolute path, then an explicit path if the command contains /, then a PATH scan producing an absolute path. The absolute-path requirement matters: the PTY layer resolves a relative program against cwd first, so a stray claude directory in your home folder would otherwise shadow the real CLI and the pane would just say [Session ended].

On Windows, resolution uses where.exe, with two special cases:

• A command that is already an existing explicit path is used verbatim.
• For codex, the npm .cmd wrapper is preferred, and a WindowsApps openai.codex_… executable is skipped entirely — that packaged GUI app is not a PTY CLI and cannot be spawned (Access is denied).
• bash falls back to known Git-Bash install locations before where.

A resolved .cmd is spawned as cmd.exe /c <path>, which is why the process tree — not just the direct child — has to be killed on close.

Approvals in a terminal pane#

PacketBench watches PTY output for the CLI's own approval prompts. When one is detected an amber overlay appears at the bottom of the pane:

Approval needed — Allow (y) · Deny (n) · Abort (Esc)

The buttons write y\n, n\n and \x03 (Ctrl-C) into the PTY respectively.

Bare y / n / Esc also work, under a strict ownership rule:

• Exactly one pane waiting → it owns the keypress, focused or not.
• Several waiting → only the active pane answers. Click a pane to make it active, or use its on-screen buttons.
• Several waiting and none active → nobody answers.

The shortcut never fires while focus is in an <input> or <textarea> (which includes xterm's own focus holder).

Terminal rendering#

The emulator is xterm.js with the fit, web-links, unicode11 and WebGL addons.

Two rendering workarounds are worth knowing about, because they explain symptoms you may have seen in other tools:

• DECRQM is stubbed out. xterm 6.0.0's bundled requestMode handler throws in minified builds, which aborts the whole parse. Any stream containing a DECRQM query then renders nothing — which is why opencode panes were blank while claude/codex were fine. PacketBench registers a no-op handler; the CLI simply gets no mode-support reply and handles that gracefully.
• WebGL is attached lazily. A WebGL canvas attached to a hidden or 0×0 container comes back permanently blank. PacketBench only attaches once the container is visible, and recreates + force-repaints it on the hidden→visible transition.

Resizes are debounced through a ResizeObserver that refuses degenerate dimensions: a hidden workspace reports 0×0, and fitting the PTY to that scrambles full-TUI CLIs on return.

Session lifecycle and failure modes#

Closing a pane, restarting it, or unmounting it all kill the PTY. Process ids are recorded at spawn so a crash or force-quit that never reaches the exit handler gets swept on the next launch.

Session tabs, status and memory capture#

Each live PTY registers a session tab with a status that drives the dots you see on the workspace tab strip:

An activity strip appears under the terminal while a tool is running, showing the tool and the file it touched. Below that, claude, codex and opencode panes get a native status bar; other CLIs get none.

Sessions longer than 10 seconds are recorded into Memory when they end — stamped done for a natural exit and killed for a kill, restart or pane close. Both are real sessions, so both are captured.

The right dock#

The Workspace surface registers two dock panels; only one is visible at a time and they share a single width budget.

Keyboard shortcuts#

View-switch chords are matched on the physical key, so they work on AZERTY, QWERTZ and Dvorak layouts.

Related#

• Core concepts — how workspaces, panes and conversations relate
• Agents & conversations — the conversation tiles that can also live in a workspace
• SSH remote workspaces — running panes on a remote host
• Settings reference — CLI client detection, default shell, prompt templates
• Memory — what session capture records