Design sessions

A design session is a chat whose 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 Hive 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 is the third chat type, alongside a dedicated chat and a Notes chat. 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.

Create a design session

Select the + beside Chats in the main menu, then choose Design in the type selector at the top of the dialog. The F1 command palette also has New design session, which opens the same dialog with the type preselected.

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

Hive creates the portable workspace layout in that folder, adds a design/ subfolder, and writes the designer instructions into .hive/instructions.md. Existing files are never replaced.

Design sessions appear in the Chats section of the main menu under their workspace folder, with a palette icon on the group header. The chat header shows the same icon next to the title.

Seed from an existing project

The dialog offers an optional Seed from project picker. Pick a Project and its directory is attached as chat context before the agent starts for the first time.

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.

• 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 Full fills the pane. 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 are ignored.

Screens render in a sandboxed frame that cannot reach Hive, the app around it, or your session. Cosmetic scripts inside a mock, such as tab toggles and accordions, still run.

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 Hive Tunnel.

Command palette

While a design session is open, F1 adds:

• Refresh design preview
• Phone width, Tablet width, Full width
• Show the chat 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.
• JavaScript only for cosmetic in-screen behavior, in a small inline script, and the screen must still read correctly without it.
• 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.

These instructions live in .hive/instructions.md in the workspace. Edit that file to change how the designer works, the same way you would for any chat workspace.

How a design session behaves differently

• Edits are auto-accepted. Like a Notes chat, a design session owns its whole workspace, so it does not ask permission for every file write unless you pick a permission mode in chat settings.
• The agent has no web access. A mock has to be self-contained, so web fetch and web search are not enabled for a design session. Reference material comes from an attached project or from the conversation.
• The workspace gets a design/ folder on top of the standard portable layout described in Chats.

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:

• 32 MiB per file
• 128 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 session removes its transcript and metadata and leaves the workspace folder, including design/, on disk on every node. Remove the folder itself from Projects > Chat workspaces.