---
url: https://clusto.app/docs/chats.md
description: >-
  Create durable AI conversations with an optional workspace folder, link notes
  and default context into any chat, turn on design mode, and pin each chat to a
  cluster node.
---

# Chats

Chats are first-class AI conversations scoped to a connection profile and
replicated across that profile's cluster. The chat list shows only the active
profile's chats. Switching profiles replaces the list and clears the previous
selection, while reconnecting or switching nodes within the same profile keeps
the current chat selected. A chat can be associated with a Project, but it does
not require a Project or source repository. Each chat has a native conversation
view, a durable transcript, and either no workspace (a shared common folder) or
a replicated workspace folder of its own. There is only one kind of chat: notes
and design are things you turn on for a chat, not types you pick when you create
it. Any chat can link [notes](#work-with-notes) as context, a chat with its own
workspace folder can turn on [design mode](/design-sessions), and that folder
can hold [instructions](#workspace-instructions) and
[default context](#workspace-default-context) for every chat in it.

## Find chats in the main menu

The main menu is the only chat list. The Chats view no longer shows a second
in-page rail.

On desktop, the sidebar shows **Terminals** followed by **Chats**. The
**Chats** section lists chats grouped under their named workspace folders.
Standalone chats in custom folders appear under those folders. Older Notes
chats, which run inside the vault, keep their own **Notes** group. Chats without
a workspace have no group:
they are listed flat, directly under the Chats header, after the groups. Each
workspace header has a chevron that shows or hides its chats; click the
workspace name to open its [workspace page](#manage-a-workspace-from-its-page).
Clusto remembers the collapsed or expanded state of each section and
group separately on this device.

When you create a named workspace, Clusto puts its folder in the node's chat
workspaces folder: `clusto-chats` in the chat user's home unless **Node
settings > Session Defaults > Chat Workspaces Folder** names another one.
That workspace remains visible as an empty group and can be selected again
after its last chat is deleted, because deleting a chat leaves the folder on
disk. Clusto also leaves automatically generated per-chat workspace folders on
disk, but hides those empty folders from the Chats sidebar and workspace picker
after their chat is deleted. This prevents a deleted chat from appearing to
return under an opaque UUID or replicated workspace name. A folder you select
manually from elsewhere is grouped by that folder only while at least one live
chat references it. Deleting its last chat leaves the external folder and its
contents on disk, but removes the empty group from Clusto.

Workspace groups (the legacy **Notes** group and named workspace folders) are
listed first, with **Notes** at the top, then the other folder groups, each
sorted by name. The flat chats without a workspace follow them. Chats inside a group, and the flat chats, are
listed newest first by creation time. Each flat chat keeps its own **Delete
chat** command in the F1 palette. This order does not depend on activity, so rows stay where they are while
several chats answer at once instead of shuffling under the pointer.

On mobile, open the slide-out main menu to select a chat. The same workspace
groups and collapse controls are available there.

The **+** button beside the Chats header opens the standard New chat dialog.
Each standalone workspace row carries its own **+** as well: it opens the New
chat dialog with that workspace already selected, so a second chat lands in the
folder you started from. The legacy Notes group's **+** starts a normal chat
with the Notes vault linked as context.
When the desktop sidebar is in icon-only mode, the Chats icon opens the Chats
view.

### Open a chat in a separate desktop window

In the native desktop app, open a chat row's context menu, use the active chat's
actions, or press `F1` to open that chat in its own window. Repeating the action
focuses the existing window. The main chat view becomes a focusable placeholder
until the separate window closes. This option is not available in the web or
mobile clients. See [Separate desktop windows](/desktop-windows) for connection
and lifecycle details.

### Open a chat in a workspace pane

A chat can also sit in a pane of the Terminals split-pane workspace, next to
terminals. See [Chats in panes](/terminal-workspace#chats-in-panes). Files and
diffs you open from the right sidebar appear as tabs on that pane (see
[Built-in Editor](/editor#where-files-come-from)) and are removed when the chat
is deleted.

### Use workspace and Project group menus

Right-click a group header on desktop, or long-press it on a touch device, to
open its context menu. The F1 command palette mirrors the group actions and
includes the workspace or Project name in each command, so you can search for
the same operation without opening the main menu. Destructive palette commands
open the same confirmation dialog as the context menu instead of acting
immediately.

A chat workspace group provides:

* **New chat in *workspace*** - opens the New chat dialog with that workspace
  selected.
* **Expand workspace** or **Collapse workspace** - shows or hides its chat rows.
* **Manage workspace** - opens the workspace page. The F1 palette lists it as
  **Manage workspace *name***.
* **Rename workspace** - available for named workspaces that have
  at least one chat, but not for the Notes vault. The F1 palette lists it as
  **Rename workspace *name***.
* **Delete workspace** - available for named workspaces, but not
  for the Notes vault.

Chats have a matching [Move to workspace](#move-chats-between-workspaces) entry
in their own context menu, and the Chats header has a
[New workspace](#create-an-empty-workspace) button.

Deleting a workspace always requires confirmation. The folder is deleted on the
node that owns the workspace, and the workspace record is removed everywhere. For a non-empty workspace,
the dialog states how many chats will be deleted before Clusto removes the folder
and everything inside it. For an empty named workspace, it confirms that the
folder and everything inside it will be permanently deleted.

### Rename a workspace

Right-click the workspace folder (long-press on a touch device) and choose
**Rename workspace**, or run **Rename workspace *name*** from the F1 palette.
The dialog takes a new name and normalizes it to a lowercase slug: letters,
digits, and hyphens, up to 64 characters. Names that look generated are refused,
meaning a chat id or a slug ending in a hyphen and 8 hex characters.

The rename runs on the chat's node, which is its pinned node or the node its
agent runs on. It renames the folder on disk and re-points every chat in that
folder to the new name. Clusto refuses the rename while a reply is in progress,
and when a folder with that name already exists.

Idle agents in the workspace are stopped and start again in the new folder with
your next message. A provider that keys its conversation by folder (Claude)
starts a fresh conversation, primed with the chat history, so the switch is
transparent.

Other cluster nodes name their copy of a chat workspace after the folder you
chose on the node that created it, not after the chat title. An untitled chat
therefore keeps its workspace name on every node instead of appearing as a
folder labelled "New chat". After a rename, every node moves its copy to the
new name.

### Edit a workspace

Open the [workspace page](#manage-a-workspace-from-its-page) and press **Edit**,
or run **Edit workspace *name*** from the F1 palette. The Edit Workspace dialog
changes where the workspace lives:

* **Node** - pins every chat in the workspace to the chosen node. Agents restart
  there with their next message, the workspace files replicate there, and new
  chats in the workspace start there. This works for any workspace folder,
  including folders that were never created through **New workspace**: Clusto
  saves a workspace record for them.
* **Folder** - an absolute path on that node (use **Browse** to pick it). An
  existing folder is used as it is, for example a repository. With **Copy
  instructions and default context** on (the default), the workspace's
  [instructions](#workspace-instructions) and
  [default context](#workspace-default-context) are copied into it, and the old
  folder stays where it was. A new or empty folder receives the whole workspace,
  moved together with its files, which only works on the same disk.

Every chat in the workspace follows the new node and folder.

### Create an empty workspace

The **Chats** sidebar header has a **New workspace** button (folder-plus icon),
and the F1 palette has a **New workspace** command. Both open the New workspace
dialog, which asks for:

* **Project** (optional) - pick a Project to link it to the workspace. The
  Project's folder becomes the workspace's
  [default context](#workspace-default-context), so every chat started in the
  workspace gets the Project folder as context. Chats still run in the
  workspace's own folder, never in the Project folder itself, because
  workspaces replicate and get scaffolding files.
* **Name** - prefilled from the Project's name when you pick one. Names are
  normalized to a lowercase slug: letters, digits, and hyphens, up to 64
  characters. Each named workspace needs a unique name.
* **Node** - the node that owns the workspace. It defaults to **Settings >
  Chats > Default node**, or to the Project's node when you pick a Project.

Clusto creates the workspace folder in the chosen node's chat workspaces folder
(see above) and replicates a workspace record to the cluster. Every device
lists the workspace right away, even while it is empty and lives on another
node. Start a chat in it with its **+**, or move existing chats into it. A new
chat started from the workspace is pinned to the workspace's node.

### Move chats between workspaces

Drag a chat row in the sidebar tree onto a workspace folder to move the chat
there. Drag it onto the list of chats without a workspace to take it out of its
folder. On touch devices and without dragging, use any of these, which all open
a workspace picker dialog:

* **Move to workspace** in the chat's context menu.
* The move button on the chat row on phones.
* The F1 command **Move chat *title***, listed for every chat.

Only the chat moves. Files in both folders stay where they are, and other chats
in the old folder keep running there. The chat's agent stops and starts again in
the new folder with your next message. A provider that keys its conversation by
folder (Claude) starts a fresh conversation, primed with the chat history. Clusto
refuses the move while a reply is in progress.

Some chats cannot move:

* Notes vault chats, the Clusto Assistant, and factory chats.
* A design chat cannot move out of a workspace, because design mode needs its
  own folder.
* A workspace whose folder name was generated (a chat id) cannot receive chats
  until you [rename it](#rename-a-workspace), because other nodes only learn
  folder names you chose.

On other cluster nodes, a moved chat follows to the folder of the same name. The
old folder stays there for the chats still in it.

### Pin a chat

Right-click a chat row (long-press on touch) and choose **Pin to top**, or
**Unpin** to undo it. The F1 palette offers **Pin chat *title*** and **Unpin
chat *title***. Pinning is free on every plan and needs no release flag.

A pinned chat moves to the top of its workspace group, above your drag-reorder
order, and shows a pin icon. A pinned chat cannot be deleted: **Delete chat** in
the menu is disabled, on touch layouts the row's trash button becomes an unpin
button, and any other delete attempt refuses with a toast. A workspace that holds
a pinned chat cannot be deleted until the chat is unpinned.

Pins are stored in app preferences (`clusto-pins`) and sync to your other
devices through [cluster preference sync](/cluster-preferences) and
[account cloud sync](/cloud-sync). Terminals can be pinned too, see
[Pin a terminal](/terminal-workspace#pin-a-terminal).

### Delete an individual chat

Right-click a chat row on desktop and choose **Delete chat**. On phones and
touch layouts, use the row's delete button or open the active chat's actions
menu and choose **Delete chat**. The active desktop chat header also has a
delete button.

The F1 command palette exposes **Delete chat *title*** for every visible chat,
so the same action is searchable without opening its workspace group. Every
entry point opens the same confirmation naming the chat and warning that its
saved transcript will be permanently deleted. Nothing deletes immediately from
a right-click, touch, header, or F1 action.

A chat shown in the Terminal view reads as a terminal session, so it closes
like one: its row menu, the **Agent actions** menu and F1 offer **Close**
instead of **Delete chat**. An idle agent closes straight away, the same as an
idle terminal; one still working on a turn asks **Close '*title*'?** with
**Close anyway**. Closing removes the chat and its transcript, like delete.

A terminal Project group provides:

* **New session in *Project*** and **New chat in *Project***.
* **Manage project** - opens the project page. The F1 palette lists it as
  **Manage project *name***.
* **Edit project**.
* **Expand project** or **Collapse project**.
* **Close all sessions** - confirms the number of sessions and warns that their
  running processes will be terminated.
* **Delete project** - confirms that the Project and all its sessions will be
  permanently deleted and that associated tasks will lose their Project
  association.

Temporary working-directory groups do not have a saved Project to edit, delete,
or associate with a chat, so they only offer session and group actions. The SSH
group offers **New SSH connection** instead of **New session**, plus expand,
collapse, and close-all actions. The gear on the SSH group opens the **SSH**
tab of Locations ("Manage SSH connections").

### Manage a project from its page

In the **Terminals** section, clicking a Project folder folds or unfolds its
sessions. Click the gear button next to it to open the project page
(`/projects/<id>?show=terminals`), which lists only that project's terminals.
A folder is matched to its project by directory and node even when its
sessions were started outside the project.

Each sidebar section header has its own gear that opens the matching tab of
**Locations** (`/projects`): the **Terminals** header gear opens
**Projects** ("Manage projects"), the **Chats** header gear opens **Workspaces**
("Manage chat workspaces"), and the **SSH** header gear or SSH group gear opens
**SSH** ("Manage SSH connections"). The **+** buttons are unchanged; the SSH
**+** still opens the SSH page to connect.

The project page starts with the project's name and its **New session**,
**Edit** and **Delete** actions, then a summary line with the working
directory, node, run-as user, shell and last activity. Below it, a table lists
the project's terminal sessions with their node and start time: click a name to
open the session, or its close button to end it. **Close all** ends every one.
Opened from F1 or from Locations (`/projects/<id>`), the page also
lists the project's chats and offers **New chat**.

### Manage a workspace from its page

In the **Chats** section, clicking a workspace folder likewise folds it, and
its gear button opens the workspace page (`/chats/workspace?dir=...`). The
page shows the folder path, the workspace's **Node** and **Project**, the kinds
of chats in it, its last activity and the list of its chats, with **New chat**, **Edit**, **Rename** and **Delete** actions (see
[Edit a workspace](#edit-a-workspace)). They
follow the same rules as the group menu: the Notes vault cannot be renamed or
deleted, and deleting a workspace asks for confirmation first. Deleting removes
the workspace record and deletes its folder on the workspace's own node, not on
the node you are connected to.

An **Instructions** section above **Default context** holds free text every
chat in the workspace follows. See
[Workspace instructions](#workspace-instructions).

A **Default context** section on the page lists the files, folders and notes
every chat in the workspace sees. See
[Workspace default context](#workspace-default-context).

### Track chat activity

Each chat row shows its current state at the right edge:

* **Waiting for your answer** - an amber dot means the turn is paused on a
  tool permission or a question from the agent. Open the chat to answer it.
* **Working** - a spinner means the agent is still handling the latest prompt.
  It also shows while the agent replies on its own after a background task
  finishes, and while subagents or background shells it started are still
  running. Background tasks never block sending: the chat accepts a new message
  as soon as the turn itself is over. The background-task spinner shows only on
  the node that runs the chat's agent process; other nodes show the turn state
  only. Stop also ends a turn the agent started on its own.
* **Unread answer** - a filled dot and bold title mean a completed answer has
  not been opened yet.
* **Read** - a check mark means the latest completed answer has been opened.
  A chat with no completed answer also starts in this state.

Read state is shared across the cluster: a chat you read on your laptop shows
as read on your phone and every other device. Opening a chat marks its latest
answer as read. **Mark all chats read** in the command palette (F1) clears
every unread answer at once. An answer that finishes while
you are viewing that chat is marked read immediately only when Clusto is visible
and its window or browser tab has focus. Otherwise, the completed answer stays
unread until you open the chat again.

Each workspace header summarizes the activity inside that group, including when
its chat rows are collapsed. An amber count shows how many chats in the
workspace wait for your answer. Otherwise, it shows a spinner while any chat in
the workspace is working, or a dot when at least one answer is unread. Waiting
takes priority over working, and working over unread.

The top-level Chats control summarizes activity across every workspace. In the
desktop sidebar's icon-only mode, the status appears on the Chats icon. In the
expanded desktop or mobile menu, it appears on the Chats header. It uses the
same waiting, working, unread priority as workspace headers, so activity remains
visible even when a group or the whole Chats section is collapsed.

Read markers are stored locally for each app or browser installation. Reading
an answer on one device does not mark it as read on another device, and the
markers do not replicate with the cluster-global conversation. When a device
first gains this feature, existing completed answers are treated as read so
only later answers request attention.

## Split panes

The Chats view splits into panes the same way Terminals does, so you can read
several chats side by side. Split panes are free on every plan, Personal
included.

* **Split**: `Ctrl+Alt+Arrow` splits the focused pane right, left, down or up.
  On macOS, `Cmd` works as the `Ctrl` modifier.
* **Maximize**: `Ctrl+Alt+Enter` maximizes the focused pane or restores the
  layout.
* **Close other panes**: `Ctrl+Alt+W` keeps the focused pane and removes the
  rest.
* **Move focus or open a pane**: `Ctrl+Shift+Arrow` moves focus to the nearest
  pane in that direction. With no pane that way, it splits the focused pane
  toward the arrow and starts a quick chat in the same workspace there. While
  the composer holds text, the shortcut keeps its normal select-by-word
  meaning; in an empty composer it works as a pane key.
* **Cycle and jump**: `Ctrl+Tab` / `Ctrl+Shift+Tab` focus the next or previous
  pane, and `Ctrl+1` to `Ctrl+9` focus a pane by its number.
* **Close pane**: `Ctrl+W` closes the focused pane; the chat keeps running.
* **New chat**: `Ctrl+T` opens the New chat dialog with the focused chat's
  workspace, node and project already picked, as a new terminal starts in the
  focused session's project. The chat lands in the focused pane. In an empty
  pane split off a chat, the workspace is that chat's.
* **Quick chat**: `Ctrl+Shift+T` skips the dialog and starts a chat in the same
  workspace with the New chat dialog's defaults. It also works while you type
  in the composer. A chat linked to the Notes vault opens the dialog instead.
* **Split with a new chat**: `Ctrl+Shift+D` splits the focused pane and starts
  a quick chat in the same workspace in the new pane. In an
  empty pane it fills that pane instead. It also works while you type in the
  composer, and the `F1` palette lists it as **Split pane with new chat**.
* **Resize**: drag a divider between panes.

On desktop, the **Pane actions** button at the top right of the focused pane
offers Maximize focused pane, Split pane left/right/up/down, Auto resize panes,
Close other panes and Close pane. The same actions are in the `F1` palette under
**Chats**. On phones the pane menu is hidden, as in Terminals, and you split
from the `F1` palette.

The focused pane is the open chat. Picking a chat in the sidebar, creating a new
one, or opening one from a report or notification opens it in the focused pane,
or focuses the pane that already shows it. A new split starts empty with
a chat picker, as in Terminals: chats already in another pane are listed under
**In this layout** with their pane number, the rest under **Available**, most
recent first, followed by **New chat** and **New design session**. Use the
arrow keys and `Enter` to pick, or `Esc` to close the empty pane. Picking a
chat shown in another pane moves it here, and choosing a chat in the sidebar
fills the empty pane too. A chat appears in at most one pane. **New chat** and
**New design session** in the picker preselect the workspace of the chat the
pane was split from.

While two or more chats are in panes, the Chats sidebar marks each of them with
a small blue dot, as the Terminals list marks sessions that share a layout.

You can also drag a chat from the Chats sidebar list onto a chat pane. Dropping
in the middle of the pane shows the chat there; dropping on an edge (the outer
quarter) splits the pane and shows the chat in the new half. The pane shows a
dashed highlight labelled **Open in this pane** or **Split left/right/up/down**
while you drag. Dragging a chat that is already in a pane moves it and closes
the pane it left. Dragging a chat row onto a workspace folder in the sidebar
still moves it between workspaces. Rows are not draggable on touch screens; use
the empty-pane picker and the split controls instead. File and diff tabs can be
dragged into their own panes too, see
[Drag and drop panes and tabs](/terminal-workspace#drag-and-drop-panes-and-tabs).

Closing a pane never stops or deletes its chat. The layout is remembered per
device. See [Terminal workspace](/terminal-workspace) for the shared pane
controls, and [Chats in panes](/terminal-workspace#chats-in-panes) to mix chats
with terminals.

## Team tab

When the agent in a chat starts a [team](/teams), the chat gets a **Team** tab
beside the conversation. It lists the team's leader and workers with their
state; tap a member to open its session, or **Open team page** for the full
view. The tab appears only while the chat started a team, and it opens by
itself once on desktop when the team is created. The same tab exists for
terminal sessions in the [Terminals view](/terminal-workspace#team-tab), but not
in SSH. See [Team tab beside the conversation](/teams#team-tab-beside-the-conversation).

## Create a chat

Select the **+** beside **Chats** in the main menu. The dialog has:

* A **Chat | Design** switch at the top. **Design** starts the chat as a
  [design session](/design-sessions).
* An optional title
* **Provider**, **Model** and **Effort** on one row: Claude, Codex, OpenCode, or
  OpenRouter as the runtime provider; an optional model from the node's current
  recommended list, or a custom model id you type; and an optional effort level,
  which sets how hard the agent thinks before it answers
* Under **More options**, **Start from project**, **Workspace**, **Node** and
  **Run as**, plus, when the node has a Notes vault, the linked note. The
  collapsed row summarizes the current choices, and it opens by itself in
  Design mode, when a project is preselected, or when a workspace folder was
  chosen.

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

After you submit the dialog, the create button shows a spinner and
**Creating...** until Clusto finishes creating the chat.

After Clusto successfully creates a chat, the New chat dialog remembers its
provider and model and preselects them the next time it opens. Canceling the
dialog or a failed creation does not change the remembered selection.

To skip the dialog, choose **Quick new chat** from the F1 command palette. It
starts a chat straight away with the remembered provider and model, the
**Settings > Chats** defaults for effort, permissions, MCP servers, node and
run-as user, and **No workspace**, then opens it with the composer
focused. It has no default shortcut; bind one from the palette like any other
command.

To start a chat from a Project, pick it under **Start from project** in the New
chat dialog, or choose **New chat in *Project name*** from the F1 command
palette or a terminal Project group, which preselects it. The Project folder is
linked into the chat as [context](#attach-context), so the agent can read its
files, and the chat is associated with the Project, so it runs as the Project's
Run As User. The chat does not get a new workspace named after the Project: it
uses **No workspace** unless you pick one. The Project directory itself never
becomes the workspace, because workspaces replicate across the cluster. Use
**Clear** to start without a Project.

With the `workspace.unified` flag on, agents started in a Project from the New
dialog instead run directly in the Project's folder on its node, without a
replicated workspace; see [Unified Workspace](/unified-workspace#start-a-shell-or-an-agent).

If you leave the title blank, the chat initially appears as **New chat**. When
you send the first message, Clusto names the chat from that message's first line
right away, and the agent may replace it with a concise title on that first
turn. Entering a title keeps the name you chose.

### Choose a workspace (optional)

The Workspace picker is marked **(optional)** and offers:

* **No workspace** - the default.
* **Create a new workspace** - a new dedicated folder in the node's chat
  workspaces folder (`clusto-chats` by default).
* **Pick a folder myself** - any folder on the node.
* **Existing workspaces** - a workspace that already holds chats.

Pick a workspace when the chat's files should follow it to other nodes. A
workspace can be a new or existing folder, and Clusto creates missing
support files and directories without replacing files that are already there.

A chat with **No workspace** runs in the node's chat folder, resolved by the
daemon on the node the chat runs on. By default that is a `clusto` folder in the
home of the OS user the chat runs as, for example `/home/ubuntu/clusto` or
`C:\Users\me\clusto`. It does not sit under the Project picker's default
working directory. The folder is shared by every no-workspace chat on that node,
and its contents do not replicate with the chat, so files the agent writes there
stay on that node, while the transcript still replicates. The chat header shows
no folder label for such a chat (the pinned-node badge still shows when the chat
is pinned). Chats that need their files to follow them to other nodes should
pick a workspace instead.

To use a different folder on a node, open the Cluster view, then the node card's
**Node settings** button, then **Session Defaults > Chat Folder**. The value must
be an absolute path, and leaving it empty restores the default. It is stored as
`default_chat_dir` in that node's `config.toml`, applied live without a restart,
and announced to the cluster like the default shell and default user. It works
for remote peers too. See [Clustering](/clustering#cluster-configuration-in-settings).

**Workspace**, **Node**, and **Run as** sit behind the collapsed **More options**
disclosure. A one-line summary beside it shows the current choices, for example
"No workspace, Connected node, Node default (ubuntu)". The section opens
automatically when the dialog starts in a specific workspace, such as from a
workspace row's **+**, when a project is preselected, or in Design mode.

You can also start a chat from the Notes view. **Chat about notes** in the Notes
toolbar and **Discuss this note** start a normal chat with the open note, or the
whole vault when no note is open, already linked as context. The chat gets no
special type and no vault workspace: it runs in the folder you choose like any
other chat. See [Work with notes](#work-with-notes).

The **Design** side of the dialog's **Chat | Design** switch starts the chat as a
[design session](/design-sessions) instead: the agent designs UI as
self-contained HTML mock screens in the workspace's `design/` folder, and Clusto
renders them live in a preview pane beside the conversation. Design mode needs
a workspace folder of its own, because the `design/` screens replicate for the
live preview. Turning it on selects **Create a new workspace** and **No
workspace** is not available while it is on. You can also turn it on or off
later in Chat settings or from F1. The F1 palette has **New design session**,
which opens the dialog with design mode already on. Everything else on this
page still applies to it.

The [Clusto Assistant](/assistant) conversation is a chat of type assistant. It
lives in the assistant dialog rather than the Chats sidebar, uses the
`clusto-chats/clusto-assistant` workspace, and follows the same Run As User rules
as other chats.

OpenCode runs through its CLI and configured upstream provider. OpenRouter is a
separate native HTTP integration: Clusto streams OpenRouter responses and owns
the workspace tool loop directly. See [OpenCode setup](/configuration#opencode)
and [native OpenRouter setup](/configuration#native-openrouter-api).

## Choose the OS user for chats

Pick the account under **Run as** in the **New chat** dialog. Leave it on the
default entry and the chat runs as the OS user its **project** pins under *Run
As User*, or as the node's **Default User** when the chat has no project or the
project sets none; the default entry names the account it resolves to. A chosen
user is saved with the chat, the new workspace folder goes under that user's
home, and the agent uses that user's logins and tools. **Settings > Chats > New chats >
Run as user** preselects it for every new chat; a user that does not
exist on the chat's node falls back to the default entry. On Windows the
chat's folders likewise go under the chosen user's profile, never the
service account's. On Unix, Clusto refuses to launch a Chat when that account
would be root, so root is not offered under **Run as**. The refusal usually
means `clustod` runs as a system service and the node default is blank.

Open **Cluster**, use a node card's **Node settings** button, and choose a non-root
account under **Session Defaults > Default User** (the same value is editable
via **Settings > Cluster > Cluster Configuration** for the connected node).
Configure every node that can run Chats. The selected account must be able to
read and write the Chat workspace and must have the selected provider's
credentials when the provider uses account-local authentication. OpenCode
stores credentials per OS account, so its login must be performed as this user.
OpenRouter is different: its API key is configured on the daemon through
the cluster-wide `[openrouter].api_key`, while the selected account only controls
workspace file and command access. Use **Settings > Account > OpenRouter API**
or **F1 > Configure OpenRouter API key** to save, replace, or clear the single
write-only key for all nodes. Changes apply to the next turn without restarting
the daemons, and nodes that were offline converge when they reconnect. A node's
`OPENROUTER_API_KEY` is used only as a local fallback when no cluster key exists
and must be changed in that daemon's service environment.

If `clustod` itself already runs as a non-root account, the node default may
remain blank. A blank value means Chats inherit the daemon process user.

The workspace has to be reachable by that account. A root-installed `clustod`
proposes new `clusto-chats` folders under the **Default User**'s home rather than
`/root`, and hands every workspace folder it creates to that account. A
workspace the account cannot enter (a folder under another user's home) is
refused with an error naming the folder and the user, instead of starting a chat
that never answers.

A chat replicated onto a root-installed node that never hosted it materialises
its workspace in that node's chat workspaces folder: the **Chat Workspaces
Folder** from Node settings, else `clusto-chats` in the **Default User**'s
home, handed to that account. Replicas that landed under the daemon's own data
directory in older releases (`/root/.local/share/clusto/chat-workspaces/...`)
move themselves into that folder on the next message, so a chat stranded by the
old location repairs itself instead of failing every send.

## Portable workspace layout

Clusto creates this shared layout:

```text
workspace/
  .clusto/
    instructions.md
    skills/
    agents/
  .claude/
    skills/
    agents/
  .agents/
    skills/
  .opencode/
    skills/
    agents/
  CLAUDE.md
  AGENTS.md
```

Put provider-neutral guidance in the active state directory's
`instructions.md`. New workspaces use `.clusto`, while a workspace with the
legacy `.hive` state directory continues to use it. Clusto generates
`CLAUDE.md` and `AGENTS.md` bridges that direct Claude and Codex to the active
directory. The provider-specific directories let you add native skill and agent
files when a tool needs them; Codex reads project skills from the shared
`.agents/skills`.

Clusto creates missing support files without replacing workspace content. On
each new agent start, it also repairs `CLAUDE.md` or `AGENTS.md` when the file
still exactly matches an older Clusto-generated bridge. A bridge you edited
yourself remains unchanged.

## Read a reply

Agent replies render as Markdown in both chat and session transcripts: headings,
bold and italic text, bullet and numbered lists, tables, links, and fenced code
blocks with syntax highlighting. Streamed text renders the same way while it
arrives.

A fenced block tagged `mermaid` renders as a diagram. While a reply is still
streaming, the block stays as code until its closing fence arrives, then
switches to the diagram. A diagram shrinks to fit the message, so tap it to open
it in the diagram dialog, where you can drag and zoom it (see
[Mermaid diagrams](/terminal-workspace#mermaid-diagrams)), with its source and
a Copy source button. Reports render
`mermaid` blocks the same way.

Wide content stays inside the message instead of stretching the conversation:
code blocks and tables scroll on their own, which keeps long commands readable
on a phone. Links open in the browser. Raw HTML in a reply is shown as plain
text rather than rendered.

**Remote images load only when you ask.** An image in a reply that points at an
`https://` address does not load on its own, because an automatic load would tell
the image's host your IP address and when you viewed the message. Clusto shows a
**Load image** button with the host name instead. Click it to load that image;
the choice lasts until you close the app and applies to every copy of the same
image. An image that points at plain `http://` is shown as a link with its
description, and other schemes show only the description. Images from files on the
node still show as file previews. The same rule applies to reports and the Notes
preview. A mermaid diagram that tries to pull styles or images from another host
is not drawn and shows "Styles that load from another host are not shown".

The conversation follows new output while you are at the bottom. If you scroll
up to read an earlier message, Clusto holds that position and shows a down-arrow
button that returns to the latest message. The command palette also provides
**Jump to latest chat message**.

Every fenced code block has a **Copy** button. Use **Copy latest code block** in
the command palette to copy the last code block in the conversation without
finding it first.

### Reopen long or active chats

Opening or reconnecting to a chat loads its complete retained conversation,
regardless of transcript size. The transcript is virtualized, so a long chat
scrolls smoothly at any length and only the messages near the screen are drawn.
Browser find (Ctrl+F) therefore searches only the visible part of a very long
chat.

Clusto may omit partial streaming updates after the completed assistant message has replaced them, may shorten an oversized
tool result to a preview, and shows an image a tool returned (such as a
screenshot the agent read) as an `[Image]` placeholder, but it does not discard
user messages or completed assistant messages from history.

Each device keeps the chats you open in a local cache, so a chat you have opened
before appears at once, even after restarting the app, and the node sends only
the messages written since. A chat opening for the first time on a device shows
a loading message until its history has loaded and the conversation has settled
at the latest message. The transcript then appears in place, without showing
intermediate layouts or scroll jumps. Once open, the conversation remains
visible as new replies stream in.

The cache is limited to about 48 MB per device; the chats opened longest ago
are dropped first. Deleting a chat removes it from the cache, and deleting a
connection profile removes every chat cached for that profile.

History can arrive while a reply is still streaming. Clusto merges the saved
history with live updates by each entry's durable identity and recorded order.
Replayed entries appear once, new live entries are not lost when the history
snapshot arrives, and two real messages with identical text remain two messages.
This also prevents repeated or missing messages when a chat is opened more than
once in quick succession.

## Watch a reply as it forms

Reply text streams to a device only while that device has the chat open. The node
folds the provider's per-token lines into a few compact updates every 75 ms (about
12 times fewer bytes per token), and a chat opened mid-reply is caught up with the
partial text first. Devices that do not have the chat open get a status update at
most once a second while it works, so the chat list and badges stay current without
carrying the reply.

A running turn shows its work live: reply text appears word by word as the agent
writes it, and a summary row above it counts the reasoning and tool calls as they
happen ("4 steps - Read, Edit"). The status row below the conversation names the
current step ("Thinking", "Running Bash", "Writing reply") next to the elapsed
time.

Claude, Codex, OpenCode, and OpenRouter chats all stream reply text when their
selected model supplies incremental output. Codex chats use the Codex
app-server stream for this; terminal and team Codex sessions keep their existing
CLI execution mode.

Codex turns complete their prompt handoff before waiting for a reply. The turn
therefore starts normally or finishes with the Codex CLI's error instead of
remaining indefinitely in **Starting**.

Codex CLI diagnostics from failed tool calls are buffered until the turn
finishes. If Codex still completes the turn successfully, Clusto discards those
diagnostics instead of showing every stderr line as a separate red error. If the
Codex process itself fails, Clusto keeps the failure visible as one combined
diagnostic.

An OpenRouter turn with no configured API key finishes as failed and shows the
credential error in the chat instead of remaining indefinitely in **Starting**.
Configure the key, then send the message again.

The reasoning and tool calls themselves stay behind that summary row, while the
turn runs and after it finishes, leaving the reply itself. Click the row to
expand one turn - a running turn keeps streaming its blocks into the expanded
view.

### Choose what a chat shows

By default a chat shows each turn's answer and the progress messages the agent
writes between tool calls, so a long turn keeps every status update in view.
Thinking and tool calls are counted in the summary row, including tool errors.
The eye button in the chat header turns each kind of activity on or off for
every turn:

* **Thinking** - the agent's reasoning blocks.
* **Tool calls and results** - each tool the agent called, its input, and its
  output or error.
* **Progress messages** - text the agent writes between tool calls, such as "Let
  me check the docs".
* **Markdown source** - show replies as raw Markdown instead of rendering them.

The same switches are in **Settings > Chats** and in the F1 palette (**Show
thinking in chats**, **Show tool calls in chats**, **Show progress messages in
chats**). They apply to every chat and to the Clusto Assistant.

On wide screens the eye menu also sets the **Width** of the conversation column
and message box: **Narrow**, **Standard** (the default) or **Wide**. The same
choice is in **Settings > Chats > Width** and the F1 palette (**Chat width:
Narrow**). Phones always use the full screen width.

Live progress is never stored. The transcript keeps the completed messages, so
reopening a chat - on this node or any other node in the cluster - shows the same
conversation without the intermediate keystrokes.

If a prompt cannot launch, Clusto shows the launch error for that prompt only. It
does not carry the error into later prompts. Use the close button at the right of
the error to dismiss it immediately. A successful `clusto-runas` fallback is
launch diagnostics, not an error, so Clusto does not show it as one.

### Choose how a chat shows: Terminal or Chat

Every chat can be shown in two views. Switch from the chat header or with F1.
The view is a setting of the chat itself and replicates with it across the
cluster, so every device (desktop, Android, iOS, web) shows the chat the same
way with the same sidebar icon, and switching it on one device changes it
everywhere. A chat with no explicit view follows its project's default view,
then the global default in **Settings > Conversations**.

* **Chat** - the answers, with the agent's work folded into one summary row per
  turn, for example "Worked 2m 10s, 14 steps, 3 files changed".
* **Terminal** - an activity log that reads like the Claude Code TUI:
  * one line per tool call. A successful command or read shows only an
    "N lines" toggle on its header line, and tapping it shows the whole
    output; a failed call still shows its last lines;
  * two or more consecutive routine tool calls (reads, commands, searches and
    the reasoning between them) fold into one "+N tool calls (Bash, Read)"
    row, with the newest call still visible. Tap the row to show them. Edits,
    todos, plans, subagents and errors always stay visible;
  * diffs printed inline with an **Open diff** action; a long diff folds after
    16 rows and can be collapsed again;
  * ANSI colors in tool output, and the todo list pinned (Codex plans show
    there too);
  * permission prompts shown as numbered options you answer with `1`, `2` or `3`;
  * `Esc` interrupts the running turn, `Up` and `Down` step through your prompt
    history, `Ctrl+O` expands everything, and `[` and `]` jump between turns;
  * long prompts stay short: a long prompt in `Up`/`Down` history recalls as a
    [pasted-text token](#large-pastes-collapse-in-the-prompt-box), and a long
    sent prompt in the transcript shows its first 3 lines plus a `[+N lines]`
    toggle that `Ctrl+O` also unfolds;
  * no chat chrome: the chat header bar, the composer's Notes and Chat settings
    buttons and the feature tips are hidden. Their actions (Notes, open in
    window, view switch, Open in TUI, message view, rename, close) are in one
    **Agent actions** menu (three-dot button) at the end of the prompt line,
    next to Send, and stay in F1. Switching back to **Chat** restores the normal
    header. This keeps a headless agent TUI-like and reliable on a phone.
  * a CLI-style prompt: a single line between two rules at the terminal font
    size, with the [status line](#check-the-model-limits-and-cost-in-the-status-line)
    and the key hint under it. A new
    Terminal-view chat opens with one dim line at the top instead of a
    centered card.

Team and task agent sessions (the session detail page) use the same composer as
chats, with prompt history and slash commands, and have the same Terminal/Chat
view switch.

### Subagents

When the agent delegates work to a subagent (Claude Code's Agent or Task tool,
opencode's task tool, or Codex's spawn_agent), the chat shows a card for it in
the Chat view's expanded activity and in the Terminal view. The card shows:

* the subagent type (for example Explore) and its description;
* a live status: running, done, failed or stopped;
* tool count, elapsed time and tokens, when the provider reports them;
* the last tool it ran, or the provider's progress summary while it runs;
* its final reply, rendered as Markdown.

The subagent's own steps fold under the card behind **Show N steps**. When
several subagents run in parallel, each one's steps group under its own card
instead of interleaving. **Open subagent** opens a dialog with that subagent's
full steps. Codex shows the card and its status, but not the nested steps yet.

While subagents run, "N subagents running" appears above the usage strip in the
Chat view and in the prompt status line in the Terminal view. Tap it to list each
running subagent and what it last did. Background subagents that keep running
after the reply stay listed there.

Headless Claude chats also receive each subagent's narration and reasoning, not
only its tool calls. Clusto sets `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1` for this;
older Claude Code versions ignore it.

### Interrupt a running turn

`Esc` or the **Stop** button interrupts the running turn and keeps the agent.
Claude, Codex and OpenCode keep the conversation (OpenCode keeps the same
OpenCode session) and take your next message at once; OpenRouter still stops the
turn, and so does a sandboxed run-as account. Each OpenCode chat turn runs
through a short-lived local OpenCode server, which adds a few seconds to the
start of a turn. An interrupted turn shows
"Interrupted" instead of an error. Sending a new direction while the agent works
(steering) also interrupts the turn instead of restarting the agent.

### Change model or permission mode while the agent runs

Changing a Claude chat's model or permission mode applies to the running agent
at once, without a restart.

### Open a chat in its TUI

**Open in TUI** (chat header and F1; not available for OpenRouter) ends the
headless agent and runs the provider's own interface on the same conversation in
a terminal: `claude --resume`, `codex resume` or `opencode --session`. The
terminal runs in the chat's folder as the chat's account.

While that terminal is open the chat takes no messages and shows a banner with
**Show terminal**. After you close it, sending a message in the chat continues
the same conversation headless.

When you come back from the TUI (close the terminal, then send, retry or reopen
the chat), the Claude and Codex turns made in the TUI are copied into the chat
transcript once, under the note "Continued in the TUI. The turns below were made
there." (or "No turns were made there."). OpenCode TUI turns are not copied yet,
so the note stays "Turns made there are not shown here". A `/clear` inside the
TUI starts a new conversation, which is not copied. Reopening a chat while its
TUI terminal is open does not start a second agent.

With the `workspace.unified` flag on, the same three views (Terminal, Chat, TUI)
are chosen when you start an agent; see [Unified Workspace](/unified-workspace).
In the migrated unified workspace every "New chat" entry point opens the New
dialog on Agent instead of the New chat dialog described on this page.

### Check the model, limits and cost in the status line

A one-line status line sits under the message box of every chat and of the
Clusto Assistant, like a CLI status line. In the Terminal view it is the line
under the prompt, next to the key hint. Click or tap it to spell out the reset
times and what the cost figure means. The status line is free on every plan,
Personal included.

It starts with the current **model**: the one the running agent reported, else
the model pinned on the chat (shown with its catalog label when Clusto knows
it). The **reasoning effort** (thinking level) of the chat comes next, for
example "High effort" or "Max effort", or "Default effort" when the chat has no
pinned level and the provider's default applies. The 5-hour and weekly plan
limits follow with their reset time inline, for example "5h 42% resets 14:00".
Plugins can add their own segments, see
[Status line segments](/plugins#status-line-segments).

What the rest shows depends on what the provider reports. Anything a provider
does not report stays hidden instead of showing as zero:

* **Claude Code** - the 5-hour and weekly plan limits (percent used and reset
  time), **Limit reached** when a window is full, **Extra usage** when the
  account is drawing on overage, how full the model's context window is, and
  the cost as "~$0.42 API". That figure is what the turns would cost at API
  list prices, from Claude Code's own estimate. On a subscription plan nothing
  is charged.
* **Codex** - the 5-hour and weekly plan windows, the credit balance when the
  account has purchased credits, and context fill. Codex reports no dollar
  cost, so none is shown.
* **OpenRouter** (native) - the cost OpenRouter actually charged, summed over
  the chat, the API key's credits left (or the credits used this week for a key
  without a limit), and context tokens. There is no window percentage because
  OpenRouter does not report the window size.
* **OpenCode** - the cost at API list prices (shown as "~$x API") and context
  tokens.

A figure turns amber at 75% used and red at 90%, and gains a warning icon, so
the state never depends on color alone.

The 5-hour and weekly limits belong to the agent account, not to one chat. A new
chat on the same node, OS user and provider therefore shows the latest reading
from your other chats before its first turn. A window whose reset time has
passed is hidden until a new reading arrives.

The status line also works on old chats: Clusto reads the figures from the chat
transcript the daemon already stores.

Turn it on or off, pick its segments and set their order in any of these
places:

* **Settings > Chats > Conversations > Status line** - a master switch plus one
  row per segment: the model, the reasoning effort (thinking), the 5-hour limit, the weekly limit, context fill,
  cost and credits, and token totals. Each row has an on/off checkbox and up and
  down arrow buttons to reorder it. The 5-hour and weekly limits switch
  separately; when they are off, a tap on the line still shows them. Token
  totals are off by default; the other segments are on. Plugin segments appear
  in the same list as "`<view title>` (plugin `<name>`)" and show until you switch
  them off.
* **Status line** in the eye menu of a chat.
* **Show/Hide the status line in chats** in the F1 palette.
* **Customize the chat status line** in the F1 palette opens the settings tab
  above.

The setting syncs with your other chat display preferences.

## Files for a chat

Chats have the same right sidebar as terminals (see
[Panels per view](/file-explorer#panels-per-view)). **Files** is on by default,
and so is **Git** when the chat works in a project root. The
**Files** panel shows the chat's folder:

* A chat started in a project and working in the project root gets the full
  project tree, and the optional Git panel.
* A chat without a workspace of its own (common) shows what it was started on:
  its project, or the project folder linked as context (for example **Implement
  with agent** from GitHub or Azure DevOps). A linked project checkout gets the
  project tree and Git; a linked worktree or other folder is a plain listing.
  Only a common chat with nothing linked shows the shared chats folder.
* Any other chat folder (standalone, named workspace, notes, design) is a plain
  folder listing you can browse.

Selecting a file opens it as a tab on the chat's pane, in the same
[editor](/editor) terminals use: view and edit, save with conflict detection,
Markdown preview, and images, audio and video shown read-only. PDFs still open
in the file preview card. This works for a chat in a project root (project
files) and for a chat in any other folder (dedicated chat folders, worktrees,
notes), where files are read and written by absolute path on the node.

With the **Git** tab on, selecting a changed file opens its diff as a tab on the
chat's pane, and **Open in editor** in the diff header opens the file as another
tab (see [Git panel](/git-panel#diffs-open-as-a-tab)). Changed files also
auto-open in a background diff tab when that setting is on.

In the Chats view, press **F1** for **Show chat of focused pane**, **Next tab in
focused pane** and **Close file tab in focused pane**.
Press **F1** and run **Toggle right sidebar** (default **Ctrl/Cmd+Shift+E**) to
show or hide it. On phones, open it from the header menu with **Chat files**.

## Send files with a message

Paste images or files into the message box from the clipboard, or use the
composer paperclip and choose **Files from this device** or **Take photo** (on
iOS: **Photo library**, **Take photo** or **Files**). All add files to the message draft exactly like pasted files. Clusto shows each
file as a removable chip before sending, and a message can contain files without
any text. Normal text paste continues to insert text.

**Take photo** opens the native camera app on Android and iOS, and an in-app
webcam dialog (**Capture**, **Retake**, **Use photo**) on desktop. macOS and iOS
ask for camera permission the first time. On Linux desktop the webcam may be
unavailable because the web view denies camera access; use **Files from this
device** there instead.

Each pasted file can be up to 10 MiB. One message can contain up to 16 files and
32 MiB in total. Clusto saves accepted files under
`attachments/chats/<chat id>/` in the chat workspace, gives duplicate names a
unique suffix, and includes their workspace-relative paths in the prompt. A chat
started in a project (the agent runs in the project's own folder) saves them in
`.clusto/chat-files/<chat id>/` inside the project instead. That folder holds its
own `.gitignore`, so the files never show up as untracked in `git status`. The
sent message shows its files in the user's message bubble: images render as
inline thumbnails and other files as chips. The files follow the workspace's
normal replication behavior.

Before you send, tap or click the file name on a chip in the message box to open
the file in the preview.

Click or tap any attachment in a message bubble (an image, a PDF, or a text or
code document) to open it in a centered preview dialog. It works the same on
desktop and mobile and has a **Download** button. A file type without a preview
shows a message saying so; you can still download it from the dialog. The preview
works when the app is connected to a different node than the one running the
chat: the node that stores a pasted file records itself and the file's full path.

Every file you attach also inserts a numbered marker at the caret in the message
box: `[Image #1]` for an image, `[File #2]` for any other file. The number is the
file's position in the message's attachments, so you can write "look at
\[Image #1] then compare it with \[Image #2]". The chips above the box and the
file chips and thumbnails in the sent message show the same `#N`. Removing a
pending file removes its marker and renumbers the markers after it. The agent
receives the attached files as a list numbered `#1`, `#2` and so on, with a note
that a marker means that file. In a headless agent session (the session detail
view) each marker is replaced by the uploaded file's path in place, and files
without a marker are still appended after the text.

Text you type but do not send is kept as a draft per chat. Leaving the chat,
switching chats, leaving the Chats view or restarting the app does not lose it.
Files in the draft survive leaving the chat within the same app run, but not a
restart. Deleting a chat drops its draft.

Pasted message files differ from **Attach** context. A pasted file belongs to
one message. A file or folder added through **Attach** remains linked to the chat
until you remove it and is available to every later turn.

## Large pastes collapse in the prompt box

Pasting more than 800 characters or more than 10 lines into the prompt box of a
chat or an agent terminal collapses it to a token such as
`[Pasted text #1 +42 lines]`, like the Claude Code TUI. The full text is sent to
the agent with the message. Delete the token to drop the paste. A collapsed
paste is kept with the draft when you leave the chat or restart the app.

## Queue or steer follow-up messages

On a desktop, Enter sends the draft and Shift+Enter adds a new line. On a phone
or tablet, Enter adds a new line and the send button sends. Ctrl+Enter (Cmd+Enter
on a Mac) sends on every device.

The composer stays available while the agent is replying. Press Enter to queue
the draft after the active reply, or open the send button's menu (**Queue or
steer**) and choose:

* **Queue after this reply** - wait for the current reply to finish, then send
  the message automatically.
* **Steer the active reply now** - stop the current reply, then send the draft
  immediately as the next turn.

Queued messages appear as removable chips above the composer. The command
palette also provides **Queue current chat draft** and **Steer with current chat
draft** while a reply is active. Queued messages may include pasted files.

The queue belongs to the current app process. It survives changing chats and a
temporary reconnect in the same app run, but it is not replicated to other
clients and is cleared when the app restarts. If an automatic send fails, Clusto
keeps the message queued and reports the error.

## Approve Claude tool requests

When Claude needs permission to use a tool, Clusto shows a **Permission
needed** card as soon as the request arrives. The current turn stays paused
while you review the tool name and its complete input.

Requests float over the bottom of the conversation, just above the message
box, so they stay in view wherever you have scrolled. The chevron in the
overlay header minimizes it to a single line while you read the conversation
behind it; a new request opens it again.

Select **Allow & continue** to send approval to that chat's live Claude process
and resume the exact pending tool call. The approval is tied to the current
chat, so another chat cannot consume it. If several requests are waiting, the
card lists them together and continues each displayed request after approval.

Approving a Claude request also allows the same request for the rest of that
agent run. For example, when Claude suggests a rule for a Bash command, that
rule is applied, so the chat stops asking again for the same command. These
rules last only for the current agent run and are never written to
`.claude/settings*.json`. To be asked less often overall, change **Permissions**
in the composer chips.

## Answer a question from the agent

When Claude asks you something instead of requesting a tool (its
`AskUserQuestion` call), Clusto renders the question itself: the header, the
question text, and each option with its description. Tap an option to pick it,
tap several when the question allows multiple answers, or type your own answer
in **Other**. **Send answer** returns your picks to the paused turn, so the
agent continues with your decision rather than a bare approval.

Only answers to questions the agent actually asked are sent. Every other tool
request keeps the plain **Permission needed** card, and Clusto never lets a client
rewrite what a tool is about to run.

## When a reply fails

When a reply fails, Clusto first tries to fix it on its own and only asks you
when it cannot. Your message is never sent twice in the transcript: a retry
replaces the failed reply in place.

Fixed automatically, with a status line instead of the "Working" indicator:

* **Agent CLI too old for the model** - Clusto runs the provider's own updater
  (`claude update`, `codex update`, or `opencode upgrade`) on the chat's node as
  the chat's OS user, then sends the message again.
* **Provider busy or unreachable** - when the agent had not started any work yet,
  Clusto waits 10 seconds and tries again, then 30 seconds. A failure after the
  agent already ran tools is never retried automatically, because sending the
  message again could repeat what those tools did.

Everything else ends the reply with a card that says what happened in plain
words and offers the fixes that apply. **Details** shows the provider's own
error text.

| What happened | What the card offers |
|---|---|
| The agent CLI is not installed on the node | Chat settings (to pick another node), Try again |
| The CLI is too old and updating it failed | Use default model, Try again |
| The provider signed the node out | Sign in, Try again |
| The chosen model is not available | Use default model, Try again (or pick a model in the composer chips) |
| A usage or rate limit was reached | Try again (or pick a model in the composer chips) |
| The provider stayed busy, or the node stayed offline | Try again |
| The conversation outgrew the model's context | New chat in the same workspace |
| The agent process stopped unexpectedly | Try again |

**Try again** sends your last message again without adding it to the
transcript. It is also in the command palette as **Retry last reply**.
**Use default model** clears the chat's pinned model and retries in one step.

## Completion notifications

When a chat finishes a reply, Clusto sends the same agent-finished notification
and sound used when an agent becomes idle in a terminal. The alert follows this
device's popup, sound, and background or minimized preferences under
**Settings > Notifications**. These preferences are stored per device.

Live completion alerts relay across the cluster, so a chat running on another
node can notify the device you are using. Clusto also records the alert in the
cluster-wide durable notification log. On Android, the optional
[Background Notifications](/background-notifications) poller can therefore
surface a completed chat while the app is closed or asleep.

Opening a chat completion notification brings Clusto forward and opens the chat
that produced it.

## Chat settings

Every chat has its own agent configuration. The provider, model, effort, and
permissions sit as chips directly under the message box, and the rest is in the
Chat settings dialog (the sliders button in the composer, or **Chat settings** in
the command palette). Changing any of it restarts the chat's agent and resumes
the same conversation, so the transcript is kept.

### Composer chips

The chips under the message box show the chat's **provider**, **model**,
**effort**, and **permissions**. Picking a value applies immediately and
restarts the agent, resuming the conversation. The chips are locked while a
reply is running; stop the reply or wait for it to finish before changing them.
The chat header no longer shows the provider badge or the model.

The provider chip is read-only: a chat's provider is fixed when it is created.
Start a new chat to use another provider. The Clusto Assistant panel uses the
same chips.

### Chat settings dialog

Chat settings opens as a centered dialog with three tabs. Model, effort, and
permissions are not in it; use the chips.

* **General** - the **workspace node** pin, **Design mode** (when the
  `chat.design` flag is on), **Accept messages from other chats** (when the
  `chat.messaging` flag is on), and **Followed report tags**. When the node is
  offline or the agent is busy, a short note under the node picker says so.
* **MCP servers** - Claude chats only. See below.
* **Agent** - the subagents, skills, and slash commands the running agent
  loaded, with **New subagent**, **New skill**, and **New command** buttons.

The footer has **Make default for new chats**, **Cancel**, and **Save**. Changes
apply when you press **Save**, except **Followed report tags**, which apply at
once.

**Design mode** switches the chat between a coding assistant and a UI
designer. With it on, the agent gets the HTML mock-screen instructions and its
edits are auto-accepted. Applying the change restarts the agent and resumes the
conversation. The switch is disabled for a chat with no workspace folder (it
shows "Design mode needs a workspace folder") and while a reply is running. See
[Design sessions](/design-sessions).

**Followed report tags** list a chip for each [report](/reports) tag the chat
follows. Tap a chip to show the reports with that tag, or tap its X to stop
following it. Type a tag in the input to follow another one; suggestions come
from the tags in use. A chat follows at most 10 tags. Changes apply at once, and
followed tags replicate across the cluster with the chat. Tags are normalised
like report tags: lowercase, spaces become dashes, at most 32 characters. A
followed tag is how a new report with that tag offers **Follow up in** this chat
(see [Discuss a report in chat](/reports#discuss-a-report-in-chat)).

Your own messages render as Markdown too, so a pasted brief or a work item
description shows its headings, lists and tables. Use **Markdown source** in the
eye menu of the chat header to switch your messages and assistant replies
between rendered Markdown and copy-friendly plain text. Plain-text mode
shows the raw Markdown source, including headings, links, lists, and fenced code
markers. You can also choose **F1 > Show chat as plain text** or enable **Settings > Chats > New chats >
Plain-text chat > Show Markdown source**. The choice is remembered across chats;
use **Show rendered Markdown** to switch back.

* **Model** (chip) - the node's current recommended models for the provider, or
  a custom model id. Choose **Custom model id...** in the picker, type the id,
  and press Enter to apply it. Historical models stay out of the picker, but an
  existing chat pinned to one keeps using it. Below the picker Clusto shows the
  model the running agent actually resolved.

If the agent CLI on the chat's node is too old for the chosen model, Clusto
updates it and sends your message again. See
[When a reply fails](#when-a-reply-fails).

For Codex, the choices are every model the authenticated Codex CLI account on
that node lists (the same set `codex` offers in its own picker), newest first.
Codex's own catalog depends on the CLI version, so a node with an older Codex
CLI offers fewer models; run `codex update` on that node to unlock new ones.
The node re-reads the list every 10 minutes and the app refreshes it when a
picker opens after 5 minutes, so a Codex self-update shows up without a
restart. **Refresh** under the picker re-reads it immediately. If Clusto cannot
read that catalog, it leaves the model unpinned so Codex uses its current
default instead of offering stale bundled model ids.

Every model picker lists the models of the node that will run the agent, not
the node the app is connected to: the chat's pinned node in the New chat dialog
and chat settings, and the **Default node** under Settings > Chats. When that
node is offline, the picker says so and keeps the last list it received; you
can still type a model id.

* **Effort** (chip) - how hard the agent thinks before it answers. Higher levels are
  slower and use more of your quota. Claude offers low, medium, high, extra high,
  and max. Codex and OpenRouter offer low, medium, high, and extra high. OpenCode
  offers minimal through max. Leave it on the default to let the provider
  choose. The level is passed to Claude as `--effort`, to Codex as
  `model_reasoning_effort`, to OpenRouter as `reasoning.effort`, and to OpenCode
  as `--variant`. A model that has no matching reasoning control ignores it, and
  OpenCode applies a level only when the model defines a variant of that name.
* **Permissions** (chip; Claude, OpenCode, and OpenRouter) - the permission mode
  the agent runs under. Claude offers ask every time, auto-accept edits, auto,
  plan only, deny unless pre-approved, or bypass all checks. **Deny unless
  pre-approved** denies every tool that is not already allowed; it does not
  auto-allow anything.
  OpenCode offers auto-accept edits, auto, and plan only; plan runs OpenCode's
  plan agent, and the other two run it with `--auto`. Codex chats have no
  permission chip. OpenRouter maps plan to read-only tools,
  accept-edits to file reads and writes, and auto to the full workspace tool set.
* **MCP servers** (MCP servers tab; Claude) - every server checkbox is always
  clickable. By default the chat follows the node's own MCP configuration, which
  includes servers added later. Untick any server and the chat switches to a
  custom set: only the ticked servers start with this chat ("N of M"). The
  **Use node configuration** button returns the chat to following the node.
  Saving an MCP change restarts the agent and resumes the conversation. Servers
  come from the agent CLI's own configuration on the chat's workspace node
  (`~/.claude.json` and a `.mcp.json` in the chat workspace); Clusto never stores
  their definitions or credentials. Each row shows where the server is defined
  and whether the running agent connected to it.
* **Agent capabilities** (Agent tab) - the subagents, skills, and slash commands the running
  agent loaded. These appear once the agent has started.

When you successfully change the model for an existing chat, Clusto remembers
that model for its provider. The next new chat automatically preselects the
remembered model when you choose that provider. This automatic
model memory does not change effort, permission, or MCP settings.

**Make default for new chats** (in the settings dialog) stores the current model, effort,
permission mode, and MCP selection as the defaults for new chats. The effort default is kept per provider.
The same defaults live in **Settings > Chats > New chats** (each chat can still
change its model, effort, and permissions from the composer chips). The model and
effort defaults are one table with a row per provider and a **Model** and an
**Effort** column; a single **Refresh models** button re-reads every provider's
list. The model picker also shows only the node's current recommended models or
a custom id you type. That tab
also sets the **Default node** and **Run as user** the New chat dialog
starts from, and how much agent activity transcripts show. These defaults are
per device and sync with your other settings.

### Pin a chat to a workspace node

Pick a node under **Node** in the New chat dialog to pin a new chat from the
start; **Settings > Chats > Default node** preselects one for every new chat.
The workspace folder is then created on that node. For an existing chat, open
**Chat settings > General > Workspace node**, or find **Chat settings** in `F1`, and
select an available cluster node. The chat header shows the selected node.
The pin is saved with the chat and follows it across devices and connections
within the same cluster. It applies to this chat only, including chats with
design mode on and older Notes chats; other chats sharing its workspace folder keep their own selection.

Pinned chats run on the selected node even when your app connects through
another node. Workspace tools, context, design previews, and MCP configuration
use that node. Linked notes and older Notes chats use that node's configured
Notes vault. Choose
**Unpinned (moves if its node goes offline)** to remove the pin. An unpinned chat
is not tied to one node; see [Move between nodes](#move-between-nodes).

Stop an active reply before changing the workspace node. Changing the selection
stops the old runtime; the next open or message continues the conversation on the
chosen node. The agent keeps its memory of the chat as described in
[Agent memory across nodes](#agent-memory-across-nodes).

A pinned chat never moves. If its pinned node is unavailable, Clusto reports it
instead of silently running the chat elsewhere:

* The chat list shows the chat dimmed with a cloud-off icon (**Unavailable**),
  and the chat header shows an **Unavailable** badge.
* A banner above the message box says the chat is pinned to that node, which is
  offline, and that it continues when the node is back or you can remove the pin.
  The banner button opens **Chat settings**.
* The message box is disabled. The full transcript still opens read-only,
  because every node holds a copy.
* When the pinned node reconnects, the app reopens the chat automatically.
* A message sent to it through the daemon is refused with "This chat is pinned
  to `<node>`, which is offline. Remove the pin in Chat settings to continue on
  this node."

You can remove the pin while that node is offline, even if its last reply still
appears to be running. The chat then continues from the last synchronized
workspace on the connected node. Files that had not synced from the unavailable
node cannot be recovered by removing the pin.

### Move between nodes

An unpinned chat records the node that last ran its agent, its runtime node.
While that node is online the chat keeps running there, even when your app
connects through another node; requests are forwarded to it.

When the runtime node goes offline (shut down, crashed, or unreachable), the next
time you send a message or retry in the chat through any other node, that node
takes the chat over. It runs the agent from the replicated transcript and
workspace. When the old node comes back, it stops its own copy of the agent.

Opening a chat never takes over its running turn. A node that finds the runtime
node unreachable waits 20 seconds for it to come back, counted from the first
request that found it missing, so a chat that sat open through the outage does
not wait again. While the node is out of reach, the chat shows a banner: "The
node running this chat (*name*) is out of reach. The chat continues there when
it is back; send a message to continue it on this node instead."

Every node already holds a full copy of each chat: transcript, settings,
attachment list, and the workspace files for chats with their own workspace
folder and for Assistant chats. Chats with no workspace and older Notes chats do
not replicate their folder. Shutting a node
down therefore loses only edits that had not synced yet.

Workspace files replicate by content hash: nodes share the file list with a
SHA-256 hash per file, and each node copies only the files whose hash it does
not hold yet, from a node that has them, in 1 MiB chunks checked against the
hash. A large workspace never has to fit in memory, an unchanged file is never
sent again, and a copy cut off by a restart resumes on its own. A quick edit that
leaves a file the same size is detected too. A workspace
replicates up to 2 GiB in total and 512 MiB per file. A chat in a larger
workspace still works on its node, but its files stay there.

If a reply was still running when its node went offline, the node that takes over
closes that turn with "The node running this chat went offline before finishing
this reply. Send the message again to continue on this node." The chat no longer
stays stuck as working, and queued messages can send.

### Agent memory across nodes

Provider session files (Claude, Codex, OpenCode) live only on the node that ran
them. When a chat moves to another node, or the provider rejects a saved
conversation ID (Claude "No conversation found", Codex "no rollout found for
thread id"), Clusto starts a fresh provider conversation and gives the agent the
chat's earlier messages: your messages and the agent's text replies, newest
kept, about 40,000 characters at most. Tool calls and reasoning are not carried
over. OpenRouter chats always rebuild from the transcript, so nothing changes
for them.

### Slash commands

Type `/` in the message box to pick from every command the running agent
reported, including your own commands, plugin commands, and bundled skills.
Arrow keys move through the list. Enter or a tap runs the command, as in the
CLI; Tab completes it into the line so you can add an argument first. Commands
run exactly as they do in the CLI. If a command genuinely fails, Clusto shows the provider's
error text instead of a generic execution error.

#### Built-in commands

A headless agent never sees the interactive commands of the CLI's own TUI, so
Clusto answers these itself, in both the Terminal view and the Chat view. They
are listed first in the `/` picker with a short description, and they shadow an
agent command with the same name. Every other `/command` (for example
`/compact` or a skill) still goes to the agent exactly as typed.

| Command | What it does |
|---------|--------------|
| `/new`, `/clear` | Starts a fresh agent in the same pane with the same provider, model, effort, permissions, MCP servers, node, run-as user, workspace or project and linked context. The old agent stays in the list, and a reply in progress keeps running. The new agent keeps the Terminal or Chat view of the one it replaces. |
| `/resume` | Turns the picker into a list of the earlier agents of the same workspace (same dedicated folder, else same project, else same kind), newest first by their last answer, with that time. Sending `/resume` on its own opens the same list. Type after `/resume ` to filter by title; Enter or a tap opens the picked agent in this pane. `/resume <text>` + Enter opens the first title match. |
| `/rename <name>` | Renames the agent. `/rename` alone opens the rename dialog. |
| `/model` | Opens the chat settings (model, effort, permissions). |

`/new`, `/clear` and `/resume` appear only where the pane can switch chats:
Workspace panes and Chats view panes, not factory or company panes. The `F1`
palette has the same two actions as **Start a fresh agent in this pane** and
**Resume an earlier agent in this pane**. Free on every plan.

### Create subagents, skills, and commands

From the Chat settings dialog (Agent tab) you can create a **subagent**, **skill**, or **slash
command** without leaving the conversation. Clusto writes the file into your
user-scope agent configuration (`~/.claude/agents/<name>.md`,
`~/.claude/skills/<name>/SKILL.md`, `~/.claude/commands/<name>.md`), replicates
it across the cluster like any other agent asset, and restarts the chat's agent
so it loads immediately. Manage the full set in **Agent docs**.

## Work with notes

Every chat can use your Notes vault as context. There is no separate Notes chat
type: a chat links notes or whole note folders the same way it links any other
file, and the agent reads them from the vault. Linked notes are context for the
conversation, so a chat in a design workspace, a project workspace or no
workspace at all can still work from your notes.

The composer shows two controls whenever the chat's node has a Notes vault
configured (see [Notes](/notes)):

* **Notes** opens the attachment picker inside the vault, so notes and note
  folders attach the same way any other file does (see
  [Attach context](#attach-context)). Linked notes and folders are chat
  attachments: they appear as chips above the message box, stay linked until you
  remove them, and every turn sees them.
* **Browse** opens the vault browser. Selecting a note opens it in the Notes
  editor.

Both controls are hidden when the node has no vault, and the New chat dialog
tells you to configure the Notes vault before it links a note.

Start from the Notes view to link a note when you create the chat. **Chat about
notes** (toolbar and F1) and **Discuss this note** start a normal chat with the
open note, or the vault, linked as context. They open the standard New chat
dialog, so you choose the provider, model and workspace as usual.

Chats created before this change as Notes chats keep working. They run with the
vault as their working directory, appear in the **Notes** group of the sidebar,
and their edits are the same files shown in Notes. No new Notes chats are
created.

## Attach context

**Attach** (the paperclip button in the composer, next to the chat settings
button) opens a menu with **Files from this device**, **Take photo** and
**Link from a node...**, plus **Add to workspace defaults...** in a chat with its
own workspace folder. The file entries add files to the message draft (see
[Send files with a message](#send-files-with-a-message)). **Link from a node...**
opens the picker described here and links files, folders and notes into the chat
as context; **Add to workspace defaults...** opens the same picker but links
them to the whole workspace (see
[Workspace default context](#workspace-default-context)).
Attachments are per chat, not per message: they stay linked until you remove
them, every turn sees them, and they replicate to every cluster node along with
the conversation.

The picker browses **any node in the cluster**, not just the one you are
connected to. Switch nodes from the header to keep adding from another machine
in the same pass - the chips at the bottom carry across nodes, and one **Add**
links the lot. Requests travel over your existing daemon connection and are
forwarded peer to peer, so a node reachable only through the Clusto Tunnel or
Tailscale works the same as one on your LAN.

How the agent reads an attachment depends on where it lives:

* **On the node running the chat** - the agent opens it directly with its own
  file tools. No copy is made and no size limit applies.
* **On another node** - files are fetched through the `clusto-chat-context` MCP
  server, which Clusto starts for every CLI-provider chat automatically.
  Attaching a single file also snapshots it immediately; attaching a folder
  records its file tree, and individual files are pulled on demand and cached as
  they are read.

### Built-in chat MCP tools

Every durable chat receives a base Clusto instruction that explains its built-in
chat, attachment, and Notes tools. Clusto wires the permanent
`clusto-chat-context` MCP server into every Claude, Codex, and OpenCode chat,
regardless of whether the chat already has a title or any attachments. No user
MCP configuration is needed.

The built-in server receives the active daemon endpoint and authentication
credential from the chat session. It does not fall back to the run-as user's
local daemon configuration, so these tools continue to address the daemon that
started the chat when the agent runs under another OS account.

Native OpenRouter exposes equivalent daemon-managed functions and sends their
calls through the same bridge. The tools therefore behave consistently across
all four chat providers:

| Tool | Input | Behavior |
| --- | --- | --- |
| `clusto_set_chat_title` | `title` | Renames the current chat. Clusto asks an untitled chat to choose a concise 3 to 7 word title before its first answer. Titles are trimmed, limited to 64 characters, and may not contain control characters. |
| `clusto_list_context` | none | Lists every attached file and folder, its owning node and label, current reachability, cached snapshot time, and folder tree. Agents should call it before reading cross-node context and again after an offline read. |
| `clusto_read_context_file` | `path`, optional `node_id` | Reads one attached file from another node. `path` must exactly match a path reported by `clusto_list_context`; `node_id` is needed only when that path is ambiguous. An offline node returns the last cached copy marked stale with its snapshot time, or reports that no copy is available. |
| `clusto_list_notes` | none | Lists files and folders in the Notes vault so the agent can discover note paths. |
| `clusto_search_notes` | `query` | Searches Notes and returns matching paths, lines, and surrounding text. |
| `clusto_read_note` | `path` | Reads a UTF-8 Markdown note and returns its SHA-256 value for concurrency-safe updates. |
| `clusto_write_note` | `path`, `content`, optional `base_sha256` | Creates a Markdown note, or updates an existing note only when `base_sha256` matches the value from the latest `clusto_read_note` call. |

The context reader is not a general remote filesystem API. It accepts only
paths already attached to the current chat. Files on the node running the chat
remain available through the provider's normal file tools instead.

Notes tools are available in every chat, not only Notes chats. An OpenRouter
chat in plan mode does not get `clusto_write_note`.
To change an existing note, the agent must read it immediately before writing
and pass the returned SHA-256 as `base_sha256`. Clusto rejects a stale or missing
SHA instead of overwriting a concurrent edit. The agent can then read the note
again, incorporate the newer content, and retry. `base_sha256` is omitted only
when creating a new path.

### Workspace instructions

The workspace page has an **Instructions** section, above **Default context**,
where you write free text that every chat in the workspace follows. It shows and
edits the file `.clusto/instructions.md` in the workspace folder. Clusto loads
that file on every turn of every chat in the workspace, through the folder's
`CLAUDE.md` / `AGENTS.md` bridge, so a change applies to the next message with
no restart.

* Type your instructions, then click **Save** or press Ctrl+S or Ctrl+Enter.
  **Revert** discards unsaved edits and restores the saved text.
* The text can be up to 256 KiB.
* Only workspaces with their own folder (dedicated workspaces) have
  instructions. A workspace needs at least one chat before you can edit them.
* When you ask an agent to "create context for this workspace", it writes to
  this same file, so its text appears in the section for you to read and edit.

Instructions and [default context](#workspace-default-context) do different
jobs. Instructions are text you write: rules, tone, project background. Default
context is a list of links to existing notes, files and folders that chats can
read; it holds no free text of its own (it is stored in
`.clusto/context.json`). Use instructions to tell the agent how to work, and
default context to point it at material to work from.

Workspace instructions are available on every plan, including Personal (free).

### Workspace default context

A chat workspace folder can hold default attachments: files, folders and notes,
on any node. Every chat in that workspace sees them on every turn, including
chats created before the default was added. Removing a default removes it from
all of those chats. Use it for material every chat in a project needs, such as
a brand guide, a spec folder or a notes folder, instead of attaching it again
to each new chat.

Add defaults in either place:

* The workspace page (**Manage workspace**), in the **Default context**
  section.
* The chat's attach menu, with **Add to workspace defaults...**. It opens the
  same picker as **Link from a node...** and adds the picks to the workspace
  instead of the chat.

In the composer, workspace defaults show as chips marked **Workspace**. A chip
links to the workspace page; remove a default there, not from the chip. The agent reads defaults the same
way as chat attachments, including snapshots for offline nodes (see below).

A workspace created with a [Project](#create-an-empty-workspace) starts with
that Project's folder as a default.

The defaults are stored in the workspace folder at `.clusto/context.json`, so
they replicate with the workspace to the other nodes. Only chats with their own
workspace folder support defaults: a chat with no workspace shares the node's
chat folder and has none.

### When a node goes offline

Attaching does not require the owning node to be up, and a node going down after
you attached never blocks the chat:

* Chips mark an offline attachment, and hovering shows when its snapshot was
  taken.
* The prompt tells the agent it is looking at a snapshot from that time, so it
  can say so instead of presenting stale content as current.
* Anything with no cached copy is reported as unavailable rather than silently
  dropped - the agent is told not to guess at the contents.
* When the node comes back, the next message re-reads it live. Nothing to
  re-attach and nothing to reconfigure.

Snapshots are cached per node under the daemon's data directory
(`<data_dir>/chat-context/<chat id>/`) and are deleted with the attachment.
Only the attachment list replicates across the cluster - never the file
contents, since each node caches independently from the node that owns the path.

A chat holds up to 64 attachments. Folder walks skip build and dependency
directories (`.git`, `node_modules`, `target`, `dist`, and similar) and stop at
4000 files or 12 levels deep.

## Conversation lifecycle

Chat metadata, transcript lines, and provider resume IDs are stored by the
daemon and replicated to every cluster node. Dedicated workspace contents
replicate with the chat. The node's shared chat folder used by chats with no
workspace does not replicate, so its files stay on the node that wrote them. Older Notes chats instead resolve the Notes vault directory
on each node and rely on Notes S3 sync when cross-node file synchronization is
configured, avoiding a second copy of the vault in chat replication.

Chats survive app disconnects and daemon or node restarts. When Clusto needs a
new hidden runtime session on the same node, it resumes the provider
conversation when the provider supplied a conversation ID. Clusto saves that ID only after the provider
confirms that the remote conversation exists.

An authentication failure before the provider creates a conversation does not
leave a resume ID behind. After authentication is restored, the next prompt can
start a new provider conversation. If the provider rejects a saved conversation
ID because that conversation no longer exists (Claude "No conversation found",
Codex "no rollout found for thread id"), Clusto persistently clears the stale
ID and retries the exact prompt once in a fresh conversation. That conversation
is seeded with the chat's earlier messages, as in
[Agent memory across nodes](#agent-memory-across-nodes). A recovered
transport failure is not added to the transcript, and the cleared ID stays
cleared across daemon restarts.

Any cluster node can reopen the chat. A workspace pin routes its runtime to the
selected node, which must be available; an unpinned chat moves to the node you
are connected to when its own node is offline (see
[Move between nodes](#move-between-nodes)). The app also reopens the selected chat
after its connection returns, so a daemon restart or reconnect does not clear
the conversation from the screen.

Transcript capture starts before the runtime emits its first output and keeps
recording throughout the conversation. If a live subscriber falls behind,
Clusto recovers the missing events from saved output instead of silently
skipping them. Chat events retain their full timestamp precision, so rapid
text, tool, and completion events remain in the correct turn even when they
share a millisecond.

Long chats render incoming changes incrementally instead of sorting and
rebuilding the entire conversation on every streaming update. While you are at
the bottom, the view follows new output as message heights change, including
on narrow screens. Scrolling up intentionally keeps your reading position;
new output does not pull you back down.

Use **Stop** to interrupt the current response. The saved chat remains available
and Clusto creates another runtime session when needed.

Renaming a chat changes its display title. Chats created without a title are
named from their first message immediately; the agent may refine the name once.
You can rename them at any time. Deleting a chat stops its runtime and permanently removes its metadata and
saved transcript. Middle-clicking a chat row opens the same delete
confirmation. Clusto deliberately leaves workspace folders
and their contents on disk on every node.

With the unified workspace (`workspace.unified`) migrated, the **Workspaces** tab
is gone and these folders are projects; see
[Unified Workspace](/unified-workspace#locations-after-the-migration).

To remove a workspace folder itself, open **Locations** (in the
**Common** folder of the main menu, or the workspace page) and select the
**Workspaces** tab (`/projects?tab=workspaces`, the gear on the **Chats**
header, or **Manage chat workspaces** in the F1 palette). That table lists
every named `clusto-chats` folder alongside
the folders live chats still use, and deleting one there removes the folder, its
contents, and any chats still running in it. The Notes vault is listed for
reference and cannot be deleted from that view. Each table fits the window and
scrolls on its own, with the column headers pinned.

Deleting a Project does not delete chats associated with it. Their transcripts
and portable workspaces remain intact, and the Chats section continues to show
them.

On narrow and mobile screens, long workspace paths are truncated in the chat
list. The **New chat**, rename, and delete controls remain available without
horizontal scrolling.

## Dedicated workspace replication

For a dedicated-workspace chat, the node where you create it uses the folder you
selected. Each peer materializes the replicated contents at a safe node-local
workspace path in its chat workspaces folder: the absolute folder set under
**Node settings > Session Defaults > Chat Workspaces Folder** (stored as
`chat_workspaces_dir`), else `clusto-chats` in the home of the OS user the chat
runs as (the **Default User**'s home on a root-installed node), the same folder
the app creates named workspaces in. Only a daemon with no home folder at all
falls back to `chat-workspaces` under its Clusto data directory. Changing the
setting affects new workspaces only; existing chats keep their folder. Local
absolute paths are never copied between nodes.

Changes replicate as they happen, at most once every 5 seconds per workspace,
and carry only the files that were added, changed or removed. A node that
missed a change, or joins later, fetches the whole workspace once and then
follows the changes again.

Workspace snapshots skip symlinks and standard generated or cache trees:
`.git`, `node_modules`, `target`, `.docker-cache`, `.gradle`, `.next`, `dist`,
`build`, `vendor`, `.cargo`, `__pycache__`, `.venv`, and `venv`. A file with more
than one name (a hard link, which can point at a file outside the workspace) is
left out too and a warning is logged, so its contents never reach another node.
If the workspace folder itself, or a folder inside it, is replaced by a link, the
snapshot is refused instead of replicating what the link points at.

Replication limits are:

* 8 MiB per file
* 16 MiB of files per workspace
* 50,000 files and directories per workspace

Choose an originating workspace where the daemon's session user can read and
write. Keep large generated output outside the replicated workspace or in one
of the excluded directories.
