Skip to content

Design sessions ​

Labs

Design mode is behind the chat.design flag and off by default. Turn it on in Settings > Labs (see Feature Flags).

A design session is a chat with design mode on: its agent works as a UI designer instead of a coding assistant. It writes each screen as one self-contained HTML file in the chat workspace's design/ folder, and Clusto renders those screens live in a preview pane next to the conversation. You describe the product, the agent draws it, and the mock updates while the answer is still being written.

Design mode is a per-chat switch, not a chat type. Everything the Chats page describes still applies: the same providers and model picker, transcript, composer, attachments, streaming progress, stop, rename, delete, notifications, and cluster-wide persistence.

Turn on design mode ​

Design mode needs a chat with its own workspace folder, because the mock screens live in the workspace's design/ folder and replicate to every node for the preview. A chat with no workspace cannot use it. There are three ways in:

  • New chat dialog. Open the + beside Chats and pick Design in the Chat | Design switch at the top. The More options section opens by itself. Turning it on selects a new workspace folder, since No workspace is not available with design mode. The F1 command palette also has New design session, which opens the same dialog with design mode already on.
  • Chat settings. Open Chat settings (the sliders button in the composer) and use the Design mode switch. Applying it restarts the agent and resumes the same conversation, so an existing chat can become a design session and back again. The switch is disabled for a chat with no workspace folder.
  • F1. While a chat is open, Turn design mode on or Turn design mode off.

The dialog asks for the same details as any chat:

  • An optional title
  • Claude, Codex, OpenCode, or OpenRouter as the runtime provider
  • An optional model
  • A workspace folder on the connected node, new or existing

Clusto creates the portable workspace layout in that folder and adds a design/ subfolder. Existing files are never replaced.

A design chat appears in the Chats section of the main menu under its workspace folder like any other chat. The chat header shows a palette icon next to the title while design mode is on.

Chats that were design sessions before design mode became a switch were migrated to plain chats with design mode on, so they keep working unchanged.

Seed from an existing project ​

The dialog offers an optional Start from project picker. Pick a Project and its directory is attached as chat context before the agent starts for the first time. The session is also associated with that Project, and its workspace folder is named after it unless you type a title or folder name.

The agent then reads the real code to derive the design language before drawing anything: theme and token definitions (Tailwind config, CSS variables, theme.ts, stylesheets, colors.xml, design-system folders) plus a couple of representative screens or components. It encodes the palette, typography, spacing scale, radii, and density as its token block, recreates the app's main screen as the first mock, and matches every later screen to it.

Only the look is reproduced. Application code is never copied into the mocks.

Attaching a project is the normal Attach context mechanism, so the folder can live on any node in the cluster and can be removed or replaced later from the composer.

Chat and preview side by side ​

On desktop the conversation is on the left and the preview on the right. Drag the divider between them to change the split; it holds between 20% and 80% and is remembered on this device.

On phones the two panes share the width, so a Chat and Preview toggle appears above the conversation. Both panes stay loaded when you switch, so neither the transcript nor the rendered screen reloads on the way back.

The preview pane ​

The pane lists every screen the agent has written and renders the selected one. It appears automatically for any chat with a workspace folder once design/*.html screens exist, even when design mode is off, so a chat that produced mocks keeps showing them. To hide or show the pane for one chat, use the chat view menu (the eye button in the chat header) or F1 Hide design preview and Show design preview. The setting applies to that chat only.

  • Screen switcher - each .html file directly inside design/ is a screen. Desktop shows one chip per screen; phones show the same list as a dropdown. Files in subfolders of design/ are not screens and are not listed.
  • Entry screen - the pane opens on home.html, or index.html if there is no home.html, and otherwise on the first screen by name.
  • Device width - Phone renders the screen in a 390px frame, Tablet in 768px, and Desktop in 1280px. A frame wider than the pane is scaled down to fit, never up, so the mock still lays out at the chosen width. The choice is remembered on this device.
  • Auto-refresh - the pane refetches whenever the workspace changes, so a screen updates as the agent saves it, mid-answer. Refresh preview refetches immediately.
  • Navigation - clicking a link inside a mock switches the pane to that screen instead of opening a browser, so a multi-screen flow can be clicked through as a prototype. Links to absolute URLs do not switch screens.

Screens render in a sandboxed frame that cannot reach Clusto, the app around it, or your session. Scripts are disabled: a <script>, an inline event handler, or a javascript: link in a mock never runs. Interactions such as tab toggles and accordions work with CSS only (<details>, :target, or :checked on a hidden input), and in-page # links scroll and drive :target. Every mock is also rendered with a content security policy that blocks all external requests, so a mock cannot load remote images, fonts, or scripts or send anything over the network. A link to another screen still switches screens, after a brief blank frame while the new screen loads.

The pane reads the screens from the chat's replicated workspace rather than the local disk, so the preview works from any node in the cluster, including the web client over the Clusto Tunnel.

Command palette ​

While a chat that has a design preview is open, F1 adds:

  • Turn design mode on or Turn design mode off
  • Show design preview or Hide design preview
  • Refresh design preview
  • Preview at phone width, Preview at tablet width, Preview at desktop width
  • Show the conversation and Show the design preview (the mobile pane toggle)

What the agent writes ​

The scaffolded instructions hold the agent to a mock contract, which is what makes the preview reliable:

  • One screen per self-contained HTML file in design/, never nested, never anywhere else.
  • All CSS inline in a single <style> block, and no external requests of any kind: no CDN links, no webfonts, no remote images, no JS libraries. Icons and imagery are inline SVG or CSS shapes.
  • The design system is declared once per screen as CSS custom properties on :root (colors, font sizes, spacing, radii, shadows) and kept identical across screens, so the set reads as one product and a restyle is one edit.
  • Mobile-first: every screen must look right at 390px with no horizontal scrolling, then adapt upward, with a 1280px desktop layout when the product calls for one.
  • No JavaScript. The preview renders every screen with scripts disabled, so tab toggles, accordions, and similar behavior are built with CSS only.
  • Navigation uses plain relative anchors such as <a href="settings.html">, so every flow you should be able to click is a real link.
  • design/home.html is created or updated first; it is the entry screen.

The agent iterates in place rather than creating v2 copies of a screen, and it replies with a short summary of what changed and which screens to look at instead of pasting HTML into the chat.

The designer instructions are given to the agent as system text while design mode is on, not written into the workspace. Turning the mode off therefore leaves nothing behind in your folder. The workspace's normal .clusto/instructions.md still applies, as it does for any chat.

What design mode changes ​

With design mode on:

  • The agent gets the designer instructions. HTML mock screens in design/, each self-contained, with no JavaScript, mobile-first (see above).
  • Edits are auto-accepted. A design chat works in its own workspace, so it does not ask permission for every file write unless you pick a permission mode in the composer chips.
  • The agent has no web access. A mock has to be self-contained, so web fetch and web search are not enabled in design mode. Reference material comes from an attached project, linked notes, workspace default context, or the conversation.
  • The workspace gets a design/ folder on top of the standard portable layout described in Chats.

Turning design mode off returns the agent to its normal instructions and permissions. The design/ screens stay in the workspace and the preview pane keeps showing them.

Replication and limits ​

A design session's workspace replicates across the cluster exactly like a dedicated chat workspace, which is what lets any node serve the preview. The same replication limits apply:

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

A screen that exceeds the per-file limit is not replicated, so the preview stops updating for it. Self-contained HTML is small, but large embedded data: images are the usual way to hit the cap. Keep imagery as inline SVG or CSS, and keep unrelated large files out of the workspace.

Deleting a design chat removes its transcript and metadata and leaves the workspace folder, including design/, on disk on every node. Remove the folder itself from Locations > Workspaces (Common folder of the main menu, or the workspace page).

Clusto - remote AI coding agents over WebSocket.