# Interactive sessions Run `cluster` with no arguments to open an interactive session in your current directory: ```bash cluster ``` You type a request, and the assistant works — reading files, running commands, and proposing edits — inside the workspace you trusted at startup. The interactive UI needs a real terminal (TTY); for scripts and pipelines use [`cluster exec`](/docs/build/exec) instead. Until you start typing, the composer shows a dimmed `Build anything` placeholder so the input area doesn't look empty. ## What the assistant can do [#what-the-assistant-can-do] The model has a built-in toolset scoped to your current directory: | Tool | What it does | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shell` | Run shell commands, including long-running background processes | | `read_file` | Read a text file by line range, byte range, or surrounding code block (images are rejected — use `view_image`) | | `view_image` | View a local PNG, JPEG, GIF, or WebP image as model-visible media | | `list_dir` / `find` | List directories and find files (gitignore-aware) | | `grep` | Search file contents with [ripgrep](https://github.com/BurntSushi/ripgrep) | | `web_search` / `web_fetch` | Search the web and fetch page content through Cluster's search service (read-only, auto-approved) | | `apply_patch` | Apply edits to files | | `request_user_input` | Ask you 1–3 short multiple-choice questions when a decision can't be settled from the repo (available in plan mode; enable in default mode with `request_user_input_default_mode`) | | `spawn_agent` / `send_message` / `followup_task` / `wait_agent` / `interrupt_agent` / `list_agents` | Delegate a bounded task to a local child agent, message or follow up with it, wait for its result, interrupt it, or list active children (see [Local agents](#local-agents)) | | `list_root_agents` / `message_root_agent` | Discover other independent interactive root sessions sharing your `~/.cluster` data root and send one an asynchronous message (see [Root-agent messaging](#root-agent-messaging)) | `grep` requires [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) on your `PATH`. Background commands started with `shell` are polled and stopped by the assistant automatically. This is the core set. It also includes background-shell helpers and any tools added by your skills, MCP servers, or cloud commands. ## File mentions [#file-mentions] Type `@` in the composer to open a fuzzy file-and-directory finder scoped to your workspace. Keep typing to filter by path, use `↑`/`↓` to move the selection, `Enter` to splice the highlighted path into your message, and `Esc` to close the popup without touching what you've typed. The list includes hidden files and directories (dotfiles), not just regular ones, but still honors your `.gitignore` — anything Git ignores stays out of the picker, and `.git` itself is always excluded. Each row shows the path alongside a `File` or `Dir` label so you can tell at a glance what you're about to mention. ## Local agents [#local-agents] The assistant can delegate part of a task to a local child agent — a separate `ChatSession` that runs in the same process, under your workspace, model, and trusted root, and reports back a bounded result. Children cannot spawn their own children, and they never see your hidden conversation or full transcript. A child can be given its own working directory, model, or reasoning effort when it's spawned; it inherits yours otherwise, and stays inside your workspace either way. At most **three** child agents run at once — a fourth spawn is refused until one finishes, rather than queued. Messaging isn't root-only: a child can `send_message` its parent (address `/root`) or another active child, and use `wait_agent` / `list_agents` to wait for a reply or see who's running — only `spawn_agent`, `followup_task`, `interrupt_agent`, and restarting a finished child stay root-only. A message addressed to root is rendered as soon as it arrives, without interrupting a turn in progress, and is consumed once your session reaches its next safe boundary. While children are active, a compact `agents: N running, M completed` line appears near the working indicator, gaining `failed` and `interrupted` counts if any child ends that way and a `message(s) queued` count while mail from a child is waiting on root; it updates live and does not pollute your session transcript. This is unrelated to [`/megaplan` and `/megareview`](/docs/build/cloud), which run on a cloud VM instead of locally. ## Root-agent messaging [#root-agent-messaging] Independent **root** sessions — separate top-level `cluster` interactive sessions, each with its own model history, workspace, and session ID — can message one another directly, without a broker daemon or hosted control plane. This is distinct from [local child agents](#local-agents): a root is a whole other interactive session, not a delegated sub-task inside your own. The assistant can call `list_root_agents` to see other active root sessions sharing your `~/.cluster` data root, and `message_root_agent` to durably enqueue a message to one of them by session ID (an exact ID or an unambiguous prefix). The recipient processes the message as a synthetic peer turn in its own session and, by default (`expect_reply: true`), the sender's call returns once the recipient's response comes back; the sender can also send a fire-and-forget message with `expect_reply: false`. Delivery survives sender or recipient restarts and `/clear`, and each peer turn is persisted only in the transcript of the session that actually received it. `message_root_agent` is a mutating tool, so it is blocked in [plan mode](#plan-mode) like other write actions; `list_root_agents` is read-only and always available. ## Workspace trust [#workspace-trust] The first time you open an interactive session in a directory, Cluster blocks startup and asks you to trust it — before login, saved sessions, project instructions, or MCP servers load. The prompt is a full-screen dialog showing the resolved workspace path and a reminder that Cluster agents can read, modify, and execute files with your user permissions. Move between the two choices with `↑`/`↓` and confirm with `Enter`, or press `1` (trust and continue) / `2` (exit) to answer directly; `Esc` and `Ctrl-C` also exit. Choosing to exit aborts the run without starting a session. Where the decision cannot be saved — your home directory, for example — the dialog says so and the trust applies to that run only. If saving fails, the dialog shows the error and lets you retry or exit. Trust is recorded against the workspace **root**. Inside a git repository that root is the repository root, so trusting any subdirectory trusts the whole repo, and a linked worktree resolves back to its main repository. Accepting saves that root in `~/.cluster/config.toml` (`[projects.""]`), covering every directory beneath it; the most specific saved entry wins, so an explicitly untrusted subdirectory still overrides a trusted parent. Once a workspace is trusted, tools run directly with your normal OS user permissions — there is no per-call approval prompt and no sandbox. Manage saved trust without opening a session: ```bash cluster trust add [path] # trust a workspace (defaults to the current directory) cluster trust remove [path] # remove saved trust for a workspace cluster trust list # list every saved trust decision ``` Pass `--trust-workspace` to trust the current run only, without saving the decision — useful for a one-off session in a directory you don't want to trust permanently. It's a global flag, so it also applies to `cluster exec`, `cluster app-server`, and `cluster cron`, all of which require either saved trust or this flag since they can't prompt interactively. Trusting a workspace lets the assistant run commands and edit any file your user can access, with no per-call confirmation. Only trust workspaces you actually intend the assistant to work in. Browser tool calls are a separate, narrower boundary: the first time the assistant navigates to a new `http(s)` origin in a session, it still asks you to confirm that origin, regardless of workspace trust. Accepted origins are cached for the session. ## Plan mode [#plan-mode] Plan mode blocks mutating tools for the session — the model can still read and search, but any edit or command is denied instead of run, so you get a plan before anything touches your project. Turn it on at startup with `cluster --plan`, toggle it mid-session with `/plan` or **Shift+Tab**. In plan mode the assistant can also call `request_user_input` to ask you a few structured multiple-choice questions when a choice materially changes the plan. When the assistant submits a finished plan, it renders under a **• Proposed Plan** heading and an "Implement this plan?" prompt appears with four choices: **Yes, implement this plan** (turns off plan mode and starts implementing in the current session), **Revise this plan** (stays in plan mode and prefills the composer with a revision prompt), **Yes, clear context and implement** (turns off plan mode, clears the session, and implements the plan from a fresh context), and **No, stay in Plan mode** (dismisses the prompt with no change — also the default for `Esc`/`Ctrl-C`). ## Remote control [#remote-control] Remote control publishes the session you are sitting in so you can follow it — and reply to it — from the Cluster mobile app or from `https://cluster.app/build/` in a browser. Your terminal stays the only place work actually runs; the remote surface sends prompts and approvals to it and streams the output back. Open the inline menu with `/remote` (or its aliases `/remote-control` and `/rc`). The bare command **turns remote control on** if it was off, then shows: * the live session URL, once connected * **Show QR code** — an in-terminal QR you can scan with your phone to open the session * **Continue** — dismiss the menu and keep the session connected * **Disconnect this session** — stop publishing Navigate with the arrow keys or `1`–`3`, `Enter` to select, `Esc` to dismiss. While the menu is connecting, the link is not shown yet; it appears on its own once the session is live. To skip the menu, use the explicit forms — `/remote on`, `/remote off`, and `/remote status`. All of them take effect immediately, without restarting the TUI. ### Connection status [#connection-status] A `/rc` status indicator — the glyph, not the command — sits at the bottom-right of the footer whenever remote control is on: **muted grey** while connecting, **teal** once the session is live. It is absent when remote control is off. If the connection drops, the CLI retries on its own with a short backoff and picks up where it left off — you will see the indicator return to muted grey and then back to teal, and no prompt or interrupt is replayed twice. An expired sign-in is refreshed in place when the refresh succeeds. Reconnects are silent — the indicator alone shows retry state, even for a longer-lived outage. The CLI keeps retrying in the background automatically; run `/remote off` to stop it. The one case that still interrupts chat with a notice is a sign-in problem: "managed remote control needs authentication; run `/login` to sign in again". `/clear` and switching models both start a *new* remote session rather than resuming the old one, so the URL and QR code change; reopen the menu to get the current link. ### Activity and read receipts [#activity-and-read-receipts] While remote control is on, the session also publishes working, waiting-for-input, and approval-needed states, plus turn completion, to the Cluster mobile app and `cluster.app` — separately from the connection indicator above, which only reflects the worker link itself. After a response or prompt renders, the CLI marks it read for you across Web and Mobile too — but only once your terminal has foreground focus, or you type something new. A response that finishes while the terminal is unfocused or in the background stays unread until you bring it back to the front; typing into an earlier, already-answered prompt does not mark a later response read. Reading a message never answers a question or approves a tool on its own. Native terminal scrollback visibility (e.g. switching tabs without losing focus) isn't observable and doesn't affect read state. ### Persisting it [#persisting-it] `/remote on` and `/remote off` write the [`remote_control_at_startup`](/docs/build/config/basic#key-reference) setting, so the choice carries into future sessions. Set [`remote_control_server_name`](/docs/build/config/basic#key-reference) to control the name this machine shows under in the remote session list — it defaults to your hostname. ## Fast mode [#fast-mode] `/fast` switches the model between standard and Fast service tiers. Fast costs more and responds faster: GPT-5.6-family models accept it for lower-latency inference, billed at the gateway's premium Fast rate (see [Fast mode](/docs/llm-gateway/models#fast-mode)). The bare command opens an inline confirmation dialog showing the current tier and what Fast means. `Tab` flips the pending selection without applying it, `Enter` confirms through the same path as `/fast on|off`, and `Esc` (or `Ctrl-C`) cancels with no change. Confirming on a model that only supports standard speed shows an unavailable notice and leaves the tier unchanged. To skip the dialog, use the explicit forms — `/fast on`, `/fast off`, and `/fast status` — which apply or report instantly, same as before. ## Follow-up messages [#follow-up-messages] Type another message and press `Enter` while the assistant is still working — it queues, and the assistant picks it up as soon as the current model response and its tool calls finish, rather than waiting for the whole turn (every remaining tool call and round-trip) to complete first. In a remote-control session, an accepted follow-up starts a new remote turn while local inference continues without interruption. Queued follow-ups are handed over one at a time, in order, at each of these boundaries. A queued `!` shell command, or a message that arrived through remote control, is never delivered mid-turn — it and anything queued behind it wait until the turn finishes. The queue only pauses after `Esc`/cancel or a rejected hand-off; press `Enter` on an empty composer to resume it. See [`Esc`](#keybindings) to pull the newest queued follow-up back into the composer for editing. ## Shell mode [#shell-mode] Start a message with `!` to run a shell command directly, bypassing the model — useful for a quick command you don't need the assistant to reason about. While the composer starts with `!`, the footer shows **Shell mode** in place of the usual mode indicators, and the leading `!` itself is not sent as part of the command. Direct shell commands are attributed to you in the session history — they render as `You ran `, distinct from `Ran ` for shell calls the model itself invokes. Shell mode is unavailable with image attachments in the composer or in a remote-control session. The command runs in your working directory with live status while it runs. Press `Esc` or `Ctrl-C` to cancel it. Submit a `!` command while a model turn is active and it queues, then runs as soon as the turn finishes. Each run is saved with the session and replayed as bounded command-and-output context on your next model request, so the assistant sees what you ran and what it printed. ## Keybindings [#keybindings] | Key | Action | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Enter` | Send your message | | `!` (at start of composer) | Enter [shell mode](#shell-mode) — run the rest of the line as a direct shell command | | `Esc` | Cancel a running turn — if the composer is empty, the newest locally queued follow-up (if any) moves back into it for editing; older queued items stay paused until you press `Enter` on an empty composer | | `Esc` `Esc` (within 800ms) | With text in the composer, clear it (recoverable with `Ctrl-_`); with an empty composer, open the inline backtrack picker to jump to and edit an earlier message | | `Ctrl-C` | Legacy cancellation — clears the composer | | `Ctrl-D` | Quit (when the input is empty) | | `Ctrl-T` | Open the transcript pager (read-only viewer) | | `Ctrl-O` | Edit the current draft in your external editor (`VISUAL`, then `EDITOR`, then `nvim`/`vim`/`vi`/`hx`/`nano`) | | `Ctrl-_` (also `Ctrl-Shift--`) | Undo the last composer edit, including a `Ctrl-C` or `Esc Esc` clear | | `Ctrl-Y` | Restore the last killed text (e.g. after `Ctrl-W`) | | `Shift+Tab` | Toggle plan mode | Clearing a non-empty draft with `Ctrl-C` or `Esc Esc` is recoverable: the footer shows a brief "`ctrl-_` undo cleared input" hint for a few seconds, and `Ctrl-_` brings the draft back. Shell results stay compact in the chat viewport — six lines at the head and six at the tail — while the pager shows the fuller completed output, including after resuming a session. This applies to background process control results (wait, input, and stop) as well as the initial `shell` call, so following up on a long-running command shows the same complete transcript, not a truncated in-progress snippet. ## Slash commands [#slash-commands] Inside a session, type `/` to see available commands. Your own [custom commands](/docs/build/config/advanced#custom-commands) from `~/.cluster/commands/` appear there too, marked with a `[Command]` badge. The full set: | Command | Action | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/model ` | Switch model | | `/effort ` | Set reasoning effort (`none`–`max`) | | `/plan` | Toggle read-only plan mode | | `/diff` | Show the working-tree git diff | | `/status` | Session summary — model and token usage | | `/compact` | Summarize older context to free up room | | `/resume` | Browse and switch sessions | | `/clear` (`/reset`) | Start a fresh conversation | | `/stop` | Stop background shell processes | | [`/fast [on\|off\|status]`](#fast-mode) | Manage [Fast mode](#fast-mode); no arg opens an inline confirmation dialog | | [`/remote [on\|off\|status]`](#remote-control) (`/remote-control`, `/rc`) | Manage [remote control](#remote-control); no arg turns it on and opens an inline menu with the session's live URL, a QR code, and Continue/Disconnect actions | | `/theme [name]` | Choose syntax highlighting colors; no arg opens a searchable picker with a live diff preview | | `/appearance [light\|dark]` | Choose the terminal appearance palette; no arg opens the picker | | [`/changelog`](/docs/build/updates#release-notes-after-an-update) | Show bundled release notes — the full release history | | `/skills` | Browse your custom skills | | `/mcp` | Inspect and manage MCP servers — reconnect, enable/disable, and authenticate without restarting | | `/goal ` | Set a persistent goal the assistant works toward | | `/loop ` | Schedule a recurring run | | [`/memory`](/docs/build/memory) | Browse and manage cross-session memory | | [`/remember [global\|project] `](/docs/build/memory) | Pin a durable memory immediately | | [`/forget `](/docs/build/memory) | Find and delete a memory after confirmation | | [`/megaplan `](/docs/build/cloud#megaplan) | Plan against your repos on a cloud VM | | [`/megareview`](/docs/build/cloud#megareview) | Launch a cloud multi-agent code review | | `/quit` (`/q`) | Exit | ## Next steps [#next-steps] * **[Exec & sessions](/docs/build/exec)** — run prompts non-interactively and resume saved sessions. * **[Config basics](/docs/build/config/basic)** — switch models, set reasoning effort, and configure [MCP servers and skills](/docs/build/config/advanced). * **[Cloud features](/docs/build/cloud)** — `/megaplan` and `/megareview` in depth.