--- url: https://clusto.app/docs/assistant.md description: >- Ask the built-in Clusto Assistant for help with setup, reports, failed tasks, cluster state, and configuration, and send feedback to the Clusto team. --- # 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](#action-cards) 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](/chats#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](/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](/configuration#native-openrouter-api). 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](/chats#choose-the-os-user-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`](/cli#clusto-docs-read-the-user-documentation). * 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](/tasks) * updating [reports](/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.