Skip to content

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 as context, a chat with its own workspace folder can turn on design mode, and that folder can hold instructions and 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. 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 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. Files and diffs you open from the right sidebar appear as tabs on that pane (see Built-in Editor) 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 entry in their own context menu, and the Chats header has a New 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 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 and 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, 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, 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 and account cloud sync. Terminals can be pinned too, see 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). 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.

A Default context section on the page lists the files, folders and notes every chat in the workspace sees. See 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.

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

Team tab ​

When the agent in a chat starts a team, 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, but not in SSH. See 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.
  • 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, 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.

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.

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.

The Design side of the dialog's Chat | Design switch starts the chat as a design session 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 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 and native OpenRouter setup.

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

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). 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 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). 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 happenedWhat the card offers
The agent CLI is not installed on the nodeChat settings (to pick another node), Try again
The CLI is too old and updating it failedUse default model, Try again
The provider signed the node outSign in, Try again
The chosen model is not availableUse default model, Try again (or pick a model in the composer chips)
A usage or rate limit was reachedTry again (or pick a model in the composer chips)
The provider stayed busy, or the node stayed offlineTry again
The conversation outgrew the model's contextNew chat in the same workspace
The agent process stopped unexpectedlyTry 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 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.

Followed report tags list a chip for each report 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).

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.

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.

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.

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.

CommandWhat it does
/new, /clearStarts 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.
/resumeTurns 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.
/modelOpens 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 opens the attachment picker inside the vault, so notes and note folders attach the same way any other file does (see 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). 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). 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:

ToolInputBehavior
clusto_set_chat_titletitleRenames 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_contextnoneLists 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_filepath, optional node_idReads 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_notesnoneLists files and folders in the Notes vault so the agent can discover note paths.
clusto_search_notesquerySearches Notes and returns matching paths, lines, and surrounding text.
clusto_read_notepathReads a UTF-8 Markdown note and returns its SHA-256 value for concurrency-safe updates.
clusto_write_notepath, content, optional base_sha256Creates 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 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 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. 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). 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.

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.

Clusto - remote AI coding agents over WebSocket.