Chats

Chats are first-class, cluster-global AI conversations. 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 a replicated dedicated workspace or the Notes vault.

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 every chat grouped under its named workspace folder. The Notes vault has its own Notes group, and standalone chats in custom folders appear under those folders. Select a workspace header to show or hide its chats. Hive remembers the collapsed or expanded state of each section and group separately on this device.

When you create a named workspace, Hive puts its folder under hive-chats. 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. Hive 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 Hive.

Workspace groups are listed with Notes first and the folder groups sorted by name, and the chats inside a group are listed newest first by creation time. 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 Notes group's + preselects the Notes vault. When the desktop sidebar is in icon-only mode, the Chats icon opens the Chats view.

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.
• Delete workspace - available for dedicated and Design workspaces, but not for the Notes vault.

Deleting a workspace always requires confirmation. For a non-empty workspace, the dialog states how many chats will be deleted before Hive 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.

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 terminal Project group provides:

• New session in Project and New chat in Project.
• 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.

Track chat activity

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

• Working - a spinner means the agent is still handling the latest prompt.
• Unread answer - a filled dot and bold title mean a completed answer has not been opened on this device.
• Read - a check mark means the latest completed answer has been opened on this device. A chat with no completed answer also starts in this state.

Opening a chat marks its latest answer as read. An answer that finishes while you are viewing that chat is marked read immediately only when Hive 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. It shows a spinner while any chat in the workspace is working. Otherwise, it shows a dot when at least one answer in the workspace is unread. Working takes priority when both states exist in the same group.

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 spinner-then-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.

Create a chat

Select the + beside Chats in the main menu, then provide:

• An optional title
• 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
• A dedicated workspace folder on the connected node, or Notes vault

To associate the new chat with a Project, choose New chat in Project name from the F1 command palette. The dialog shows the Project association, but still asks for the chat's own workspace. Association is metadata only: the chat does not inherit the Project directory and keeps its independent portable workspace.

If you leave the title blank, the chat initially appears as New chat. After you send the first message, the selected provider chooses a concise title from that message and updates the chat automatically. Entering a title keeps the name you chose.

A dedicated workspace can be a new or existing folder. Hive creates missing support files and directories without replacing files that are already there. The Notes option uses the node-local vault configured in Notes settings.

You can also start a Notes chat from the Chat button in the Notes toolbar. The same New chat dialog opens with Notes vault selected, and the open note is prelinked when one is selected.

Choosing Design in the type selector creates a design session instead: the agent designs UI as self-contained HTML mock screens in the workspace's design/ folder, and Hive renders them live in a preview pane beside the conversation. Everything on this page still applies to it.

OpenCode runs through its CLI and configured upstream provider. OpenRouter is a separate native HTTP integration: Hive streams OpenRouter responses and owns the workspace tool loop directly. See OpenCode setup and native OpenRouter setup.

Choose the OS user for chats

Durable Chats run as the OS user their project pins under Run As User, and as the node's Default User when the chat has no project or the project sets none. The New chat dialog prints the account it resolves to. On Unix, Hive refuses to launch a Chat when that account would be root. This often happens when hived is installed as a system service and the node default is blank.

Open Cluster, use a node card's Configure action, 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 OPENROUTER_API_KEY or [openrouter].api_key, while the selected account only controls workspace file and command access. Use Settings > Appearance > OpenRouter API or F1 > Configure OpenRouter API key to inspect the redacted source status and save, replace, or clear the private config key. Changes apply to the next turn without a daemon restart. An environment key must be changed in the daemon's service environment.

If hived 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 hived proposes new hive-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 node that never hosted it materialises its workspace in the same place: hive-chats under the Default User's home, owned by that account. Replicas that landed under the daemon's own data directory before this (/root/.local/share/hive/chat-workspaces/... on a root-installed node) 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

Hive creates this shared layout:

workspace/
  .hive/
    instructions.md
    skills/
    agents/
  .claude/
    skills/
    agents/
  .codex/
    skills/
  .opencode/
    skills/
    agents/
    agent/
  CLAUDE.md
  AGENTS.md

Put provider-neutral guidance in .hive/instructions.md. CLAUDE.md and AGENTS.md direct Claude and Codex to that shared file. The provider-specific directories let you add native skill and agent files when a tool needs them.

Hive only creates missing files. Existing CLAUDE.md, AGENTS.md, and other workspace content remain 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.

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.

The conversation follows new output while you are at the bottom. If you scroll up to read an earlier message, Hive 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.

Watch a reply as it forms

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.

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 - or turn on Show agent activity in Settings > Chat to keep every turn expanded.

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, Hive 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 Hive does not show it as one.

Send files with a message

Paste images or files into the message box from the clipboard. Hive 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.

Each pasted file can be up to 10 MiB. One message can contain up to 16 files and 32 MiB in total. Hive 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. The sent message keeps file chips in the transcript. The files follow the workspace's normal replication behavior.

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.

Queue or steer follow-up messages

The composer stays available while the agent is replying. Press Enter to queue the draft after the active reply, or open Send... 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, Hive keeps the message queued and reports the error.

Approve Claude tool requests

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

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.

Answer a question from the agent

When Claude asks you something instead of requesting a tool (its AskUserQuestion call), Hive 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 Hive never lets a client rewrite what a tool is about to run.

Completion notifications

When a chat finishes a reply, Hive 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. Hive 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 Hive forward and opens the chat that produced it.

Chat settings

Every chat has its own agent configuration, reachable from the sliders icon in the chat header, the model shown next to the title, the composer, or the command palette. Changing any of it restarts the chat's agent and resumes the same conversation, so the transcript is kept.

• Model - the node's current recommended models for the provider, or a custom model id you type. Historical models stay out of the picker, but an existing chat pinned to one keeps using it. Below the picker Hive shows the model the running agent actually resolved.
• Permissions (Claude, OpenCode, and OpenRouter) - the permission mode the agent runs under. Claude offers ask every time, auto-accept edits, auto, plan only, do not ask, or bypass all checks. OpenCode offers auto and plan. OpenRouter maps plan to read-only tools, accept-edits to file reads and writes, and auto to the full workspace tool set.
• MCP servers (Claude) - either use the node's own MCP configuration, or pick servers. Picking servers starts the agent with exactly those, and nothing else, however the node is configured. Servers come from the agent CLI's own configuration on the connected node (~/.claude.json and a .mcp.json in the chat workspace); Hive never stores their definitions or credentials. Each row shows where the server is defined and whether the running agent connected to it.
• Agent capabilities - 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, Hive 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 permission or MCP settings.

Save as default stores the current model, permission mode, and MCP selection as the defaults for new chats. The same defaults live in Settings > Chat, where the model picker also shows only the node's current recommended models or a custom id you type. These defaults are per device and sync with your other settings.

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 or a tap select one; Tab or Enter completes it. Commands run exactly as they do in the CLI. If a command genuinely fails, Hive shows the provider's error text instead of a generic execution error.

Create subagents, skills, and commands

From chat settings you can create a subagent, skill, or slash command without leaving the conversation. Hive 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

A Notes chat is a normal chat, not a separate Notes-only agent. It appears in the chat rail with a Notes badge and uses the shared provider and model picker, transcript, composer, streaming progress, permission controls, Stop action, rename, delete, persistence, and resume behavior.

The composer adds Notes controls when a Notes chat is open:

• Notes opens the attachment picker inside the vault, so notes attach the same way any other file does (see Attach context).
• Browse opens the vault browser. Selecting a note opens it in the Notes editor.
• Ask the selected agent to browse, create, or update files. The agent's working directory is the vault, so its edits are the same files shown in Notes and synchronized through the normal Notes sync process.

Attach context

Attach in the composer links files and folders into the chat as 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 Hive 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 hive-chat-context MCP server, which Hive starts for the 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

Hive wires the hive-chat-context MCP server into a chat automatically when the title is empty or the chat has attachments. No user MCP configuration is needed. It exposes these tools:

Tool	Input	Behavior
hive_set_chat_title	title	Renames the current chat. Hive 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.
hive_list_context	none	Lists every attached file and folder, its owning node and label, current reachability, cached snapshot time, and folder tree. Agents should call it before reading cross-node context and again after an offline read.
hive_read_context_file	path, optional node_id	Reads one attached file from another node. path must exactly match a path reported by hive_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.

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.

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. 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 Hive needs a new hidden runtime session, it resumes the provider conversation when the provider supplied a conversation ID. Hive 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 Claude rejects a saved conversation ID because that conversation no longer exists, Hive persistently clears the stale ID and retries the exact prompt once in a fresh conversation. 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. 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.

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

Renaming a chat changes its display title. Chats created without a title are named automatically after the first message, and you can rename them at any time. Deleting a chat stops its runtime and permanently removes its metadata and saved transcript. As with terminal sessions, middle-click an individual chat row to close and delete it immediately. Hive deliberately leaves workspace folders and their contents on disk on every node.

To remove a workspace folder itself, open Projects. Its Chat workspaces section lists every named hive-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.

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 under its Hive data directory. Local absolute paths are never copied between nodes.

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.

Replication limits are:

• 32 MiB per file
• 128 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.