Interactive sessions

Run cluster with no arguments to open an interactive session in your current directory:

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 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

The model has a built-in toolset scoped to your current directory:

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

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

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, which run on a cloud VM instead of locally.

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: 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 like other write actions; list_root_agents is read-only and always available.

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."<canonical-root>"]), 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:

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.

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 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 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/<session-id> 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

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

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

/remote on and /remote off write the remote_control_at_startup setting, so the choice carries into future sessions. Set remote_control_server_name to control the name this machine shows under in the remote session list — it defaults to your hostname.

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).

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

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 to pull the newest queued follow-up back into the composer for editing.

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 <command>, distinct from Ran <command> 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

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

Inside a session, type / to see available commands. Your own custom commands from ~/.cluster/commands/ appear there too, marked with a [Command] badge.

The full set:

Next steps

• Exec & sessions — run prompts non-interactively and resume saved sessions.
• Config basics — switch models, set reasoning effort, and configure MCP servers and skills.
• Cloud features — /megaplan and /megareview in depth.