Skip to content

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:

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. The markers below appear on its rows too.

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 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 for how agents report it and Terminal Notifications, Progress and Bell for the notification, progress and bell signals.

Session colors and titles ​

With color rules set up in Appearance, 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 and account cloud sync. Pinned chats work the same way, see Pin a chat.

Team tab ​

When a conversation started a team, 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 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.

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). 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. See 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. 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). 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, 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 to send Alt+Arrow up to the terminal. The same action is available as Send Alt+Arrow up in the F1 command palette.

ActionShortcut
Split in a directionCtrl+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 paneCtrl+Shift+D
Focus the nearest pane in a direction, or at the edge open one with a quick sessionCtrl+Shift+Arrow
Maximize or restore the focused paneCtrl+Alt+Enter
Close other panes and keep their sessions runningCtrl+Alt+W
Close the focused pane and keep its session runningCtrl+W
Move the active file tab into a new pane in a directionCtrl+Alt+Shift+Arrow
Close the focused sessionCtrl+Shift+W
Move the layout to a new window, or back to the main windowCtrl+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 composerCtrl+V (Cmd+V on macOS)
Paste the clipboard image into the terminalAlt+V (Option+V on macOS)
Open the Attention viewMod+Shift+A
Open the notification historyMod+I (outside text fields and terminals)
New terminalMod+T
Next or previous tabCtrl+Tab / Ctrl+Shift+Tab
Jump to tab 1 to 9Ctrl+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.

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 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.

Clusto - remote AI coding agents over WebSocket.