---
url: https://clusto.app/docs/unified-workspace.md
description: >-
  The unified Workspace sidebar that merges Terminals and Chats into one tree of
  projects, folders and pinned items, the account-wide migration, and the New
  dialog for shells and agents (behind the workspace.unified Labs flag).
---

# Unified Workspace

The unified workspace merges the **Terminals** and **Chats** sidebar sections
into one tree called **Workspace**. It is behind the `workspace.unified`
[Labs flag](/feature-flags) (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](/terminal-workspace) and [Chats](/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](/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](#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](/ssh-view)) 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](/chats#choose-how-a-chat-shows-terminal-or-chat); 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**:

1. **Preview migration** lists what would move on the connected profile, without
   changing anything.
2. **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-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.
