---
url: https://clusto.app/docs/terminal-workspace.md
description: >-
  Arrange terminal sessions and chats in split panes, move focus by keyboard,
  maximize one pane, close pane slots without stopping their sessions, get a
  warning before closing a session that still runs programs, and open Mermaid
  diagrams agents print.
---

# Terminal Workspace

The **Terminals** view can show several sessions in one workspace. Each pane is
a view of a session, so changing or closing the layout does not stop the session
on the Clusto node.

## Start a terminal

`Mod+T` (`Ctrl+T`, or `Cmd+T` on macOS) and the **+** in the **Terminals**
sidebar open one **New terminal** dialog for every kind of terminal. It has
three choices:

* **Project / node** - a shell or agent session in a project on a node.
* **SSH** - a terminal over an SSH connection. See
  [SSH Connection Manager](/ssh-view#connecting).
* **This PC** - a local shell on this computer, on the desktop app. See
  [Explorer Menu and Local Terminals](/explorer-menu).

The `F1` palette has the same entry points as **New terminal**, **New SSH
terminal** and **New terminal on this PC**.

For a project terminal the dialog asks for two things up front:

* **Project** - the Project whose folder, node and defaults the terminal uses.
  Press `Enter` in the project search to create the terminal straight away.
* **Shell** - the shell or agent preset to run.

Everything else sits behind a collapsed **More options** row: **Working
directory**, **Run As User**, **Name** and **Arguments**. The row summarizes the
current values, for example "Project folder, Node default (ubuntu)", so you can
see what the terminal will use without opening it. It opens by itself when the
caller already picked a folder. **Name** is optional; when left blank the
terminal is named from its terminal title.

Press `Ctrl+Enter` (`Cmd+Enter` on macOS) in any field to create the terminal.

With the `workspace.unified` Labs flag on, the **Terminals** and **Chats**
sidebar sections become one **Workspace** tree; see
[Unified Workspace](/unified-workspace). The markers below appear on its rows
too.

## Sidebar markers

Each session row in the **Terminals** sidebar starts with an icon for its kind
(a bot for an agent, a terminal icon for a plain shell) and shows what its
program is doing at the end of the row:

* **Amber question disc** - the agent is waiting for your answer: a permission
  prompt, an approval or a question. The session name also starts with `?`.
  Hover the row to see why it waits (permission, question, sign-in). Claude
  Code, Codex and any tool that reports through the
  [waiting marker contract](/agent-attention) set it.
* **Spinner** - the agent is working. A Claude Code session that ended its turn
  while background shells or sub-agents are still running keeps the spinner
  until the last background task finishes.
* **Green check mark** - the agent finished its turn and is neither working nor
  waiting for an answer. It clears when the next turn starts. The mobile
  session switcher shows it too.
* **Bell** - the terminal bell rang in a session you are not looking at.
* **Thin bar under the name** - progress the program reports.

Waiting sessions also add up where you can see them without opening anything:

* Each project folder shows an amber count of its waiting sessions, also while
  the folder is collapsed.
* The **Terminals** header (and its icon in the collapsed sidebar) shows the
  number of waiting sessions on every online node. SSH sessions count under
  the **SSH** section while it is shown.
* **Go to next waiting session** in the `F1` command palette opens the next
  one. Run it again to cycle through all of them.

The marker clears as soon as the agent continues. See
[Agent Waiting-for-Input Marker](/agent-attention) for how agents report it and
[Terminal Notifications, Progress and Bell](/terminal-notifications) for the
notification, progress and bell signals.

## Session colors and titles

With color rules set up in [Appearance](/appearance#session-colors-and-titles),
a session row in the **Terminals** sidebar shows a colored stripe, the pane tab
shows a colored dot, and the mobile session switcher shows the dot beside each
session. A title template changes how sessions are named in the same places.

## Pin a terminal

Pin a terminal to keep it at the top of its list and stop it being closed by
accident. Pinning is free on every plan and needs no release flag.

* In the **Terminals** and **SSH** sidebar trees, each row has a pin button.
  On desktop it appears on hover; on touch layouts it is always visible.
* Press `F1` and run **Pin or unpin terminal** (Workspace group) for the active
  terminal, or **Pin terminal *name*** / **Unpin terminal *name*** for any
  session.
* Pinned rows move to the top of their folder, above your drag-reorder order,
  and show a pin icon.
* A pinned terminal cannot be closed. The close button is hidden, and
  middle-click, the `F1` **Close session** command and the session list and
  detail kill actions all refuse with "This terminal is pinned. Unpin it to
  close it."
* **Close all** in a folder closes everything except pinned terminals and says
  how many it kept.

Pins are stored in app preferences (`clusto-pins`), so they follow you to your
other devices through [cluster preference sync](/cluster-preferences) and
[account cloud sync](/cloud-sync). Pinned chats work the same way, see
[Pin a chat](/chats#pin-a-chat).

## Team tab

When a conversation started a [team](/teams#team-tab-beside-the-conversation),
a **Team** tab appears beside it in the **Chats** and **Terminals** views (not
SSH). It shows the team roster with each member's state, and tapping a member
opens its session. The tab is shown only while the conversation started a team,
and it opens by itself once on desktop when a new team is created. The `F1`
palette has commands to open and close it.

## Quick new session

`Ctrl+Shift+T` skips the New dialog and starts what the dialog would start with
a plain Enter. With the unified workspace on (`workspace.unified`), that is the
kind of the focused pane first: a focused agent gives another agent with the
same provider and view (Terminal or Chat). Otherwise it is whatever you last
created in that project with **Create** in the New dialog. If the last thing
you created in a project was an agent in the Terminal view, `Ctrl+Shift+T`
starts another agent there with the same provider, model, effort and view, shown
in the focused pane. A shell project still gets a shell. From the Chats view,
`Ctrl+Shift+T` on an agent starts another agent in that agent's project.
Without the unified workspace it always starts the last-used shell. **Split
with new terminal** (`Ctrl+Shift+D`) and restarting a lost terminal always
start a shell.

## Split and focus panes

Use `Ctrl+Alt+Arrow` to split the focused pane in the arrow's direction. Click
or tap a pane to focus it, or use `Ctrl+Shift+Arrow` to move focus to the nearest
pane in that direction. With no pane that way, `Ctrl+Shift+Arrow` splits the
focused pane toward the arrow and starts a quick session there, as
`Ctrl+Shift+D` does.

Press `Ctrl+Shift+D` (`Cmd+Shift+D` on macOS) to split the focused pane and
start a quick session in the new pane: same node and project as the focused
terminal, with the shell you last picked. The pane splits
along its longer side, so right on a wide pane and down on a tall one. In an
empty pane the shortcut fills that pane instead of splitting it again. The
action is also **Split pane with new terminal** in the `F1` command palette,
where you can bind it to a different key.

The focused pane has a highlighted border. Session and terminal actions apply
to that pane.

## Maximize the focused pane

Press `Ctrl+Alt+Enter` to make the focused pane fill the workspace pane area.
Press it again to restore the full split layout.

This is a non-destructive workspace view mode, not operating-system fullscreen.
The split layout remains intact, and the other terminal panes stay loaded and
continue receiving output while hidden. Splitting or closing a pane exits the
maximized view.

## Close other panes

Press `Ctrl+Alt+W` to keep the focused pane and permanently remove all other
pane slots from the current layout. The sessions shown in those panes keep
running and remain available from the **Terminals** navigation tree.

Closing a pane is different from closing a session:

* **Close pane** removes only the pane slot and keeps its session running.
* **Close other panes** removes every pane slot except the focused one and keeps
  all sessions running.
* **Close session** stops the session on its node.

## Warning before closing a busy session

Closing a session asks its owning node what still runs inside it. This covers
the X in the **Terminals** sidebar, the mobile switcher's close, `Ctrl+Shift+W`,
the `F1` **Close session** command, and **Close** on the project page. If the
agent is working or waiting for an answer, a program reports progress (OSC
9;4), or the process tree holds running programs, a "Close '*name*'?" dialog
lists them with **Close anyway** and **Cancel**. An idle session closes
immediately with no prompt.

The list shows jobs of the shell, either foreground (`vim`, `npm run dev`) or
backgrounded with `&`, and shell commands the agent started (Claude Code Bash
tool calls and background shells, Codex commands), marked with a bot icon. The
session's own shell, the agent CLI, run-as wrappers, console hosts, the agent's
MCP and language servers, and the session's own command (such as `ssh` in an
SSH session) are not listed.

The check works on Linux, macOS and Windows nodes, and sessions on other
cluster nodes are asked on their owner. If the node cannot be reached within 5
seconds, Clusto still warns based on the agent's working, waiting and progress
states. `Ctrl+W` (close pane) is unchanged, and the **Close all** project action
keeps its own confirmation. Deleting a chat whose agent turn is still running
says so in the delete confirmation.

## Pane actions menu

On desktop widths, open the three-dot **Pane actions** menu in the top-right
corner of the focused pane to use the same controls with a mouse or touch. The
button is hidden on phone widths to keep the mobile action bar unobstructed.
The menu can:

* Maximize the focused pane or restore the split layout.
* Split left, right, up, or down.
* Auto-resize panes to balance the layout.
* Close the focused pane or all other panes.

The maximize and multi-pane actions are disabled when the layout contains only
one pane. You can also find **Toggle focused pane maximize** and **Close other
panes** in the `F1` command palette.

On the native desktop app, the same pane menu can open the focused terminal in
its own window. The pane becomes a focusable placeholder until that window is
closed. The terminal session keeps running throughout. See
[Separate desktop windows](/desktop-windows) for lifecycle and connection
details.

On the desktop app the menu can also move the whole layout
into its own window (**Move layout to new window**, `Ctrl+Shift+O`), and a
torn-out window offers **Move back to main window**. See
[Tear out a layout or a node](/desktop-windows#tear-out-a-layout-or-a-node).

## Chats in panes

A pane can hold an agent chat as well as a terminal session or an SSH session.
Files and Git diffs open as tabs on the pane of the session or chat they belong
to (see [Built-in Editor](/editor)). An empty pane shows a picker titled "Select a session or chat
for this pane". It lists the terminal sessions first, then **Chats**: the 8 most
recent, with **Show N more chats** for the rest. Arrow keys and `Enter` move
through all items, sessions and chats alike.

* **New chat** sits beside **New terminal** in the picker. It opens the usual
  New chat dialog, and the chat it creates opens in that pane. The `F1` palette
  has the same action as **New chat in focused pane**.
* A chat pane shows the full chat: header, transcript, composer, design preview,
  settings, attachments, and the option to open the chat in a new window.
* While a chat pane is focused, the usual chat commands are available in the
  `F1` palette inside the workspace: stop, retry, jump to latest, rename,
  settings, attach, the design preview toggles and the rest.
* A chat sits in one pane of a layout at a time. Picking it in another pane moves
  it there.
* Putting a session into a chat pane replaces the chat.
* Closing the pane keeps the chat; nothing is deleted. Deleting the chat clears
  it from every pane that showed it.
* Session actions such as **Close session**, **Rename session** and the key bar
  do nothing while a chat pane is focused.

The Chats view has its own split panes with the same shortcuts and menu; see
[Split panes](/chats#split-panes). See [Chats](/chats) for the chat itself.

## Drag and drop panes and tabs

Drag and drop is free on every plan, Personal included. It works with the mouse
on desktop; on touch screens use the buttons and shortcuts listed below.

While you drag, the pane under the pointer shows a dashed highlight with a
label. The middle of a pane's content area means **Open in this pane**. The
outer quarter on a side means **Split left**, **Split right**, **Split up** or
**Split down**, and the dragged item opens in the new half.

### Drag a session or chat onto a pane

* Drag a session from the **Terminals** or **SSH** sidebar list onto a pane.
  Dropping in the middle shows it in that pane; dropping on an edge splits the
  pane and shows it in the new half.
* Dragging a terminal or chat that is already in a pane moves it, and the pane
  it left closes. This is how you rearrange the layout. Drag the pane's main
  tab (the terminal or chat tab in the tab strip) to do the same.
* Chats can be dragged from the Chats sidebar onto a chat pane in the Chats
  view with the same rules, see [Split panes](/chats#split-panes). Dragging a
  chat row onto a workspace folder still moves it between workspaces.

### Tabs and file panes

Files and diffs open as tabs of their terminal or chat pane (see
[Built-in Editor](/editor)). A file or diff tab can also live in its own split
pane, a **file pane**:

* Drag the tab onto the edge of any pane's content area to split that pane and
  show the tab in the new half. Drag it onto the middle of a pane to move the
  tab into that pane's tab strip.
* Drag a tab within its strip to reorder it, or onto another pane's tab strip
  to move it there.
* The split button at the right end of the pane tab strip moves the active tab
  to a new pane: to the right on a wide pane, below on a tall one such as a
  phone. This is the touch path.
* `Ctrl+Alt+Shift+Arrow` moves the active file tab into a new pane in that
  direction. The `F1` palette has **Move file tab to new pane on the right**,
  **on the left**, **below** and **above**. On GNOME desktops the OS may take
  `Ctrl+Alt+Shift+Arrow` for workspace switching; the palette and the split
  button still work.

A file pane has no terminal or chat. It closes by itself when its last tab is
closed or dragged away. Closing a file pane (`Ctrl+W`, **Close pane**) moves its
tabs into the pane that takes focus, so nothing is lost, including unsaved
edits. Putting a terminal or chat into a file pane keeps its tabs as tabs of
that terminal or chat.

On touch screens rows and tabs are not draggable, because a long-press opens
menus. Use the split button, the empty-pane picker and the existing **Move**
button instead.

## Session lost on its node

When the node that owns a terminal session no longer has it (the node
restarted while the session was not in a holder process, see
[Terminals that survive a restart](/remote-updates#terminals-that-survive-a-restart),
or the session was killed there), the pane shows "Session not found
on *node* - input is paused" with **Reconnect** and **New session** buttons.
Input to that pane is blocked while the banner is shown, so nothing you type
disappears into a dead console. **Reconnect** tries to attach again; **New
session** opens a fresh terminal in the same pane. The same recovery is
available as **Reconnect terminal** in the `F1` command palette.

From the CLI, `clusto attach`, `clusto open`, and `clusto send` exit non-zero
with an error when the session is gone on its node.

## Switch and rename sessions on mobile

On phone widths the workspace top bar shows a session switcher (for example
"Project / Session 1/3"). Open the dropdown to pick a session, and tap the pencil
button beside a session to rename it. On any width, **Rename session** in the
Terminals group of the `F1` command palette renames the focused terminal.

The bar lists the same projects and rows, in the same order, as the sidebar
Workspace tree, headless agents included. The previous and next arrows step
through a project's terminals and agents together, picking an agent opens it,
and picking a project opens its first terminal or agent (a project that holds
only agents appears in the project dropdown too). An agent opened on a phone
shows the same bar above it, so you can jump to the project's other sessions
without opening the sidebar, and its **New** entry opens the New dialog on the
agent's project. Agent rows have no rename or close buttons in the dropdown;
rename and delete stay in the agent's own menu.

## Mermaid diagrams

When an agent prints a Mermaid diagram in a terminal, Clusto detects it. Claude
Code shows a bare `mermaid` label line above the indented source (its renderer
drops the fences); other CLIs may print the raw ` ```mermaid ` fence. The label
becomes a link, underlined on hover. Click or tap it to open a **Mermaid
diagram** dialog with the rendered diagram, the source (collapsible), and a
**Copy source** button.

The diagram opens fitted to the dialog. Drag to move it, scroll the wheel or
pinch to zoom around the pointer, and double-click to zoom in. The toolbar in
the corner zooms out and in, shows the zoom level (click it for actual size),
and fits the diagram back to the view. With the diagram focused, `+` and `-`
zoom, `0` fits, `1` shows actual size, and the arrow keys move it.

To open the newest diagram in the active terminal's scrollback, run **Render
Mermaid diagram** (Terminal group) from the `F1` command palette. If there is no
diagram, it shows a notice.

Limits: a Claude Code style block ends at the first blank line. If the program
hard-wrapped a long source line, the diagram may fail to parse. The dialog then
shows the parse error with the source below it.

## Keyboard reference

On mobile, open the **More** row of the terminal [key bar](/terminal-key-bar)
to send `Alt+Arrow up` to the terminal. The same action is available as **Send
Alt+Arrow up** in the `F1` command palette.

| Action | Shortcut |
| --- | --- |
| Split in a direction | `Ctrl+Alt+Arrow` |
| Quick new session (same kind as the focused pane or your last Create) | `Ctrl+Shift+T` |
| Split and start a quick session in the new pane | `Ctrl+Shift+D` |
| Focus the nearest pane in a direction, or at the edge open one with a quick session | `Ctrl+Shift+Arrow` |
| Maximize or restore the focused pane | `Ctrl+Alt+Enter` |
| Close other panes and keep their sessions running | `Ctrl+Alt+W` |
| Close the focused pane and keep its session running | `Ctrl+W` |
| Move the active file tab into a new pane in a direction | `Ctrl+Alt+Shift+Arrow` |
| Close the focused session | `Ctrl+Shift+W` |
| Move the layout to a new window, or back to the main window | `Ctrl+Shift+O` |
| Show or hide the right sidebar (Terminals, Chats, SSH) | `Ctrl+Shift+E` |
| Copy the selection (without a selection it interrupts, see below) | `Ctrl+C` |
| Paste text, files or a screenshot into the terminal or chat composer | `Ctrl+V` (`Cmd+V` on macOS) |
| Paste the clipboard image into the terminal | `Alt+V` (`Option+V` on macOS) |
| Open the Attention view | `Mod+Shift+A` |
| Open the notification history | `Mod+I` (outside text fields and terminals) |
| New terminal | `Mod+T` |
| Next or previous tab | `Ctrl+Tab` / `Ctrl+Shift+Tab` |
| Jump to tab 1 to 9 | `Ctrl+1` to `Ctrl+9` |

### Paste, attach and drag files

`Ctrl+V` (`Cmd+V` on macOS) pastes text into a terminal. When the clipboard
holds files or a screenshot, Clusto uploads them to the node and types their
path, the same as dropping them on the pane. `Alt+V` (`Option+V` on macOS) sends
the clipboard image to the terminal explicitly. In a chat composer `Ctrl+V`
attaches pasted files and images to the message. Dragging files onto a pane
works too. See [Send files to a terminal](/file-explorer#send-files-to-a-terminal).

## Diagnostics and the latency overlay

The **Diagnostics** card in **Settings > Terminal** has a **Latency overlay**
switch (**Show the terminal latency overlay**, also in the `F1` palette) and a
**Renderer** override with **Automatic**, **WebGL** and **DOM**. The override
applies to terminals opened after the change; use it only to compare renderers
while chasing a slow terminal. Both settings stay on the device. See
[Troubleshooting](/troubleshooting#_22-typing-in-a-terminal-feels-slow) for how
to read the overlay.

Under **Measured on this device** the card also shows two samples that are
always collected and never sent anywhere: **Keystroke echo** (the time from one
keystroke in twenty to the next output of that terminal, as p50, p95 and max)
and **Frame gaps** (checked for one second every ten seconds once a terminal is
open; a gap of 50 ms or more is a visible hitch). Use them to tell a slow link
from a slow device without turning the overlay on.

### Terminal output on desktop and phones

The app batches terminal output once per display frame instead of drawing every
chunk, which keeps scrolling smooth under a flood on desktop and mobile. On a
phone, terminals that are not on screen stop streaming and resume when you
return to them, so background terminals no longer receive output.

### Ctrl+C on a line with unsent input

`Ctrl+C` with text selected copies it. Without a selection it interrupts the
foreground program, which in Claude Code and most shells also clears the
message you are typing. To keep a slip next to `Ctrl+V` from wiping that
message, Clusto holds the first `Ctrl+C` while the line has input you typed or
pasted and not yet submitted, and shows "Press Ctrl+C again to interrupt".
Press it again within 2 seconds to send it. On an empty line, for example to
stop a running command, one press interrupts at once.
