Subshell Docs

Workspaces

A workspace is the window of panes you work in. Launches land as tabs in one, and a workspace holds references to the running subshells rather than copies of them.

How they fit together

A subshell is the session; a workspace is how you arrange sessions. The same subshell can sit in several workspaces at once, because a workspace holds a reference, not a copy. Closing a pane in a workspace removes that reference and leaves the session running; closing the subshell itself ends it everywhere (see Session lifecycle).

Launch your first subshell and you're in a workspace, named after it, with nothing to save. Removing its final tab retires the workspace, and the session keeps running unfiled. Closing the subshell itself is a separate action and can remove a workspace when no panes remain.

Open and land

The sidebar’s Workspaces selector switches between workspaces and offers New workspace. Below it, the sidebar shows the active workspace’s subshells. Subshells below the workspace members lets you browse the rest without leaving the active workspace. Opening the app returns you to the workspace you were last in.

  1. Open the ⋯ menu beside the workspace selector and choose Add subshell to launch a new session into the active workspace. The new pane joins as a tab. The same action is available beside the grouping dropdown in the Subshells section.
  2. Selecting a session in Subshells adds it to the selected workspace. Included sessions appear above that section; selecting one focuses its tab. With no workspace open, selecting a session opens a workspace that holds it, or creates one. Choose Subshell dashboard from the grouping dropdown’s ⋯ menu to open the full dashboard.
  3. On a subshell’s own page, Add a subshell to a workspace opens a workspace with both subshells as tabs.

Follow subagents

Active subagents appear beneath their parent subshell. Use the arrow beneath the parent's status dot to expand or collapse them; selecting the parent row returns its terminal to the main agent when the harness supports view switching, without changing disclosure. They stay inside the parent's terminal and don't create workspace tabs. See Subagents for harness support and view switching.

Arrange the panes

In the sidebar, drag a subshell between the workspace area and Subshells to add or remove its tab. The centered drop zone says Add to workspace or Remove from workspace. Removing a tab keeps the session running. The row’s ⋯ menu offers the same actions; removing the last tab retires the workspace, and the session keeps running unfiled.

New subshells join as tabs. On a wide screen, arrange panes side by side: drag a pane's tab toward an edge of another pane and release it when the split preview appears. Each tile group has its own tab row, so tabs sit where you arranged them, not always across the top.

Workspace with a shell and test results side by side.
This workspace keeps a project shell beside its test results. Use Add subshell to include another session. Select the image to enlarge it.

On a small touch screen, the workspace presents its panes as tabs instead of side-by-side terminals. A narrow desktop window with a mouse keeps the draggable pane layout.

Rename, delete, and the empty case

Open the ⋯ menu beside the workspace picker in the sidebar and choose Rename… to change its name; the bar above the panes shows the focused terminal's own name instead. The same menu deletes a workspace outright, which drops all of its panes at once; the sessions keep running, and you can file one into another workspace by selecting it in Subshells.

Changing a layout is different from changing a session's working directory or agent settings. Use Clone and switch presets for those launch operations.

Next steps

Use Presets to repeat launch settings and Share a subshell to grant session access.

Edit on GitHub

Last updated on

On this page