Appearance
Unified Workspace
The unified workspace merges the Terminals and Chats sidebar sections into one tree called Workspace. It is behind the workspace.unifiedLabs flag (cluster scope, off by default) and is free on every plan. With the flag off, nothing changes: you keep the Terminals and Chats views described in Terminal Workspace and Chats.
The tree
- Pinned - a section at the top that holds pinned projects and folders. A pinned terminal or agent stays in its project (or folder) and moves to the top of it, with a pin icon.
- Folders - groups you make yourself. A folder can be nested inside another folder and holds projects, terminals, agents and SSH sessions. Folders are layout only: they do not exist on disk. Deleting a folder moves its contents up one level and deletes nothing else.
Pins and folders sync automatically through account cloud sync when it is enabled and unlocked: a change uploads within about 1.5 seconds and your other signed-in devices show it live when the app is shown or focused, with no restart. Without cloud sync they stay on this device. An agent's Terminal or Chat view is not part of this: it is a setting of the agent itself and replicates with the chat across the cluster, so every device shows the agent the same way, and switching the view on one device changes it everywhere. A chat with no explicit view follows its project's default view, then the global default in Settings.
- Projects - projects with nothing active are hidden by default. A project shows while it has a terminal session or an agent that is working, waiting for input, has an unread answer, is open, or was used in the last 24 hours. Pinned projects and the built-in Notes and Scratch projects always show. The Show inactive projects (N) row at the bottom of the tree brings the rest back (it becomes Hide inactive projects while shown). The same toggle is in Settings > Navigation and the F1 palette.
- SSH connections - every saved SSH connection is its own row next to the projects, with its terminal sessions listed under it. See SSH connections in the tree.
- Scratch - a built-in project for chats that have no folder.
- Notes - a built-in project for older Notes chats.
Built-in projects (Scratch and Notes) cannot be deleted.
Scratch, workspace or project
Three kinds of place hold your agents and shells:
- Scratch - zero setup. It uses the node's common chat folder, and nothing in it syncs to other nodes.
- Workspace - a named, synced folder with no folder to pick. You give it a name, the node creates the folder in its chat workspaces root, and the files sync across nodes (the project shows the Synced badge in Locations).
- Project - your own folder, for example a git repository. It stays on its node and is never replicated.
New workspace
Create a workspace from just a name with the New workspace button next to New Project on the Locations page (Projects tab), or with the F1 command New workspace. The dialog asks for:
- Name - the workspace name.
- Node - the node that creates the folder. It only shows in a multi-node cluster, and new agents in the workspace start on that node.
Once the workspace is created, the New dialog opens on Agent in it, so you go straight from a name to a running agent. Agents started in a workspace run as replicated workspace chats in its folder, so their files sync like those of migrated chats.
Every item row starts with an icon for its kind, so terminals and chats look alike:
- Bot - an agent terminal: a headless agent chat shown in the Terminal view, or an agent CLI such as Claude, Codex or OpenCode running in its own TUI.
- Terminal - a plain shell.
- Speech bubble - a chat in the Chat view. Notes, Assistant, Design and Factory chats keep their own icons.
Rows use the regular interface font, and the waiting, working or done status sits at the end of the row for terminals and chats alike. The Terminals and SSH sections use the same rows.
On phones the tree has an Agents filter that hides plain shells, so the list shows only agent sessions.
SSH connections in the tree
Each saved SSH connection (see SSH) is a row in the tree, and the terminal sessions opened through it are listed under it.
- + connects: it opens a new SSH terminal for that connection.
- The gear edits the connection.
- The row menu has Connect, Edit, Move to folder, Collapse or Expand, Close all sessions (only that connection's sessions) and Delete connection. Deleting removes only the saved connection, never the server.
Connection rows can be dragged into sidebar folders like projects. A connection with nothing active hides with the Hide inactive projects setting, and Show inactive brings it back.
The separate SSH section of the sidebar does not appear in this mode. New SSH connection and Manage SSH credentials are in the F1 palette, and the SSH target of the New session dialog still works. SSH sessions opened before the flag was on, and sessions whose saved connection was deleted, stay in an SSH group.
File rows into folders and reorder them
Drag a row to file it:
- Drop it on a folder to put it there.
- Drop it on the Drop here for the top level zone to take it out of its folder.
- Drop terminals and agents between a project's sessions to reorder them. The order is remembered.
With a mouse, just drag. On a touch screen (phone or tablet), hold a row for a moment, then drag it. A quick swipe still scrolls the list, a tap still opens the row, and holding still without moving opens the row menu. The list scrolls by itself when you drag near its top or bottom edge. Move up and Move down in a row's menu also reorder terminals and agents.
Terminal and agent rows have no Move to folder menu item or button. To file one without dragging (with the keyboard or a screen reader), press F1 and run Move name to folder, which opens a folder picker. The palette lists the same command for folders, projects and SSH connections.
Start a shell or an agent
The New dialog, opened from a project, starts either:
- Shell - a plain terminal in the project folder.
- Agent - pick the AI provider. Model, Effort and how the agent shows sit behind More options, whose collapsed row names the current choices (for example "Default model, Chat, Node default (ubuntu)"). The dialog opens with what you last used in the project, so most agents start with a plain
Enter. The views:- Terminal - headless; the activity log prints every step like a terminal, with no chat header. Notes, rename, delete and the other chat actions are in the Agent actions (three-dot) menu next to Send.
- Chat - headless; shows the answers only, with the work folded into one summary row per turn.
Every agent runs headless, so Model and Effort apply to both views. To use an agent's own TUI, start a Shell and run its CLI there (claude, codex, opencode), or use Open in TUI on an existing agent.
Ctrl+T opens the New dialog on the same kind of session as the focused pane: a headless agent on its provider and view, a shell running an agent CLI on Agent with that provider, a plain shell on Shell. From an empty pane the dialog opens on what was last started in the project.
Create starts the agent directly in the focused Workspace pane; there is no second New chat dialog. Every "New chat" entry point (F1 New chat, the project page, the + on a project in the sidebar, an empty pane, chat workspace pages) opens this dialog on Agent in that project. Scratch and Notes projects start agents in the node's chat folder, and Notes links the vault as context.
An agent started in a project runs in the project's own folder, on the project's node, as the project's Run As user, like typing claude in the repository: its CLAUDE.md and .claude skills, agents, hooks and settings load. The folder is never replicated to other nodes, re-owned, or given chat workspace files, and the chat is pinned to the project's node. Headless agents always run in the project root, so the Working Directory field is hidden for them. Clusto refuses to use a non-synced project's folder (a git checkout) as a replicated chat workspace; start the agent in the project instead.
The dialog remembers the last setup per project on this device: Shell or Agent, provider, model, effort, view and shell. A project you have never used falls back to the project's default agent and view, then the last setup used anywhere, then the Settings > Agents > New agents defaults. The old New chat dialog remains only for the pre-migration layout and design sessions, and goes away when the flag is removed.
The Terminal and Chat views are described in Chats; you can switch a headless agent between them, or move it into its TUI, at any time.
Migrate your existing chats
Moving to the unified workspace needs your approval, so nothing changes under you. You approve once for your whole account, in Settings > Labs > Unified workspace:
- Preview migration lists what would move on the connected profile, without changing anything.
- Migrate all profiles approves the move for every saved connection profile.
The connected profile migrates right away. Every other saved connection profile migrates automatically the first time any of your devices connects to it. For each profile Clusto turns the cluster's workspace.unified Labs override on (if it is off) and then runs the migration. Before it changes anything it backs up the node database beside the original as data.sqlite3.pre-unified-<timestamp>.bak.
The migration needs every connected node to run the same version and refuses to start while a chat is answering. A profile that is refused tries again the next time you connect to it, not in a loop on the same connection. It then:
- turns each named chat workspace into a project (the folder is synced across nodes);
- puts every chat into a project, with chats that have no folder going to Scratch.
Once approved, the panel shows Approved for all profiles, with a collapsible Profiles list that marks each saved profile Migrated or Waits for connect. A toast, "Profile moved to the unified workspace", appears when a profile migrates. The panel also shows in Labs when the account is approved, even if this cluster's flag is still off.
The approval is stored in the synced setting clusto-unified-workspace-migration, so it follows your account through account cloud sync (and cluster preferences). Without cloud sync it applies to this device only.
Nothing is deleted. Turning the flag off shows the old Terminals and Chats views again.
Locations after the migration
Once the flag is on and the cluster is migrated, the Locations page (/projects) has no Workspaces tab, because every chat workspace is now a project. Old ?tab=workspaces links open the Projects tab, and the F1 Show chat workspaces command is hidden. Projects whose folder syncs across nodes, such as former chat workspaces, show a Synced badge next to their name in the Projects table.
Next to New Project the Projects tab has a New workspace button, shown only while the unified workspace is active. It replaces the old New chat workspace flow: you enter a name and no folder, and you get a synced project (see New workspace). New Project is still how you add your own folder.
The Settings > Chats tab is named Settings > Agents after the migration. Its defaults (model, effort, permissions, MCP servers) are what the New dialog pre-selects when it starts an agent; the transcript settings apply to every agent shown in the Chat view.
With the flag on but the cluster not yet migrated, the Workspaces tab shows a hint with an Open migration button that leads to Settings > Labs > Unified workspace. With the flag off and no account approval nothing changes.