Clusto Assistant

The Clusto Assistant is an AI assistant built into the Clusto app. It knows which view you have open, so you can ask about what is on screen without explaining it first. Use it to:

• set up and learn Clusto
• explain a report or a failed task run
• check cluster state, nodes, and sessions
• help with node and app configuration
• send a bug report, idea, or question to the Clusto team

The assistant runs on an agent you choose (Claude Code, Codex, or OpenRouter) and never changes anything on its own. When it wants to act, it proposes an action card that you apply or decline.

Open the assistant

• Desktop: the sparkles button in the sidebar footer. It is also present in the collapsed icon-only sidebar.
• Mobile: the sparkles button in the header.
• F1 command palette:
  • Ask Clusto Assistant - open the assistant with the current view shared.
  • Reset Clusto Assistant - delete its history and pick the agent again.
  • Ask the assistant about the last error - start from the most recent app error.
  • Send feedback to the Clusto team - draft feedback with the assistant.
• Reports: a report card's More menu has Ask the assistant, and the Reports palette offers Ask the assistant about my reports.
• Tasks: the Tasks palette offers Ask the assistant why task failed for each failed task.

The assistant opens as a dialog in the middle of the window, and fills the screen on a phone. Close it with the X button or Escape; the conversation stays where you left it.

The assistant is one permanent conversation. Its history is kept, so every time you open it you continue where you stopped. The header shows the agent and model, the eye button chooses what the conversation shows (see Choose what a chat shows), and the options menu changes the model and effort.

To start over or switch to another agent, choose Reset assistant in the options menu (or F1 > Reset Clusto Assistant). After you confirm, the conversation and its history are permanently deleted and the assistant asks you to pick the agent, model and effort again.

The assistant needs a connected node. Before the app is connected, the dialog shows the steps to install a node and connect to it instead.

Choose the agent

The first time you open the assistant, pick the agent it runs on:

• Claude Code or Codex - uses the provider login on the connected node, the same as Chats.
• OpenRouter - uses the cluster-wide OpenRouter API key. Set it in Settings > Account > OpenRouter API or with F1 > Configure OpenRouter API key. See native OpenRouter setup.

You can also pick an optional model and effort level.

The conversation is a chat of type assistant. It uses the workspace folder clusto-chats/clusto-assistant and runs as the same OS user a chat would, following the Run As User rules for Chats. It lives only in the assistant dialog: it does not appear in the Chats sidebar or its unread counts, and a notification for it opens the assistant.

What the assistant sees

Each message you send carries a short summary of where you are in the app:

• the current route and view name
• the selected or open records, such as the open report, the focused terminal session, the selected chat, failing tasks, offline nodes, the active report filter, the open settings tab, or the open note
• app version, platform, and form factor (desktop or mobile)
• connection state
• recent app error lines
• the F1 commands available in that view

A chip above the composer shows what the assistant sees, for example Sees: Reports: Nightly build. Click the chip to stop sharing the view; it then reads View not shared. Secrets are never included in the view summary.

What the assistant knows

The assistant answers from:

• the Clusto user documentation embedded in the installed clusto CLI. These are the same pages as this site, matched to the installed version, and they work offline. See clusto docs.
• the clusto guide topics
• the exact CLI help for the installed version
• which Clusto MCP servers are installed for Claude Code and Codex

What the assistant can check

The assistant has read-only tools for:

• cluster status and configuration (secret values are never returned)
• sessions
• projects
• reports (list and read)
• tasks and their runs
• teams
• the tail of the daemon log (tokens redacted)

The tools are served by clusto chat mcp, which the daemon wires into assistant chats automatically. There is nothing to install, and other chats do not get these tools.

Action cards

The assistant never changes anything itself. When an action would help, it proposes one and a card shows exactly what will happen:

• Apply runs the action with your own session and permissions.
• Decline rejects it.

The outcome, applied, declined, or failed, is reported back to the assistant on its next turn. Each card resolves once and replicates with the conversation, so another device shows the same result.

The assistant can propose:

• opening a view
• creating a scheduled or one-shot shell task
• updating reports: mark read, pin, archive, or add and remove tags. The reports must be loaded in the Reports view.
• changing a node's default session user or default shell
• starting a terminal session in a project or folder
• sending feedback to the Clusto team

Send feedback

Ask the assistant to report a bug, suggest an idea, or ask the Clusto team a question, or use F1 > Send feedback to the Clusto team. The assistant drafts the message and the feedback card shows:

• the full text that will be sent
• whether diagnostics are attached: app version, platform, form factor, current view, and recent app error lines. Diagnostics are attached only if you agree.

Apply sends it to the Clusto team. Feedback works without a Clusto account. When you are signed in, it is linked to your account so the team can follow up.

Privacy and safety

• Report bodies, task output, logs, and notes are treated as data, never as instructions to the assistant.
• Tokens and API keys are redacted from everything the assistant reads.
• The view summary never includes secrets, and you can turn it off with the context chip.
• Every change goes through an action card that you apply yourself.

Customize the assistant

Edit .clusto/instructions.md in the assistant workspace (clusto-chats/clusto-assistant) to add your own preferences, such as answer style or language. Clusto's built-in assistant instructions are supplied separately and update with the app, so your file is never overwritten.