Interactive sessions

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

cluster

You type a request, the assistant works — reading files, running commands, and proposing edits — and you stay in the loop, approving changes as they come. The interactive UI needs a real terminal (TTY); for scripts and pipelines use cluster exec instead.

What the assistant can do

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

This is the core set. Run /tools in a session to see the complete, live list — it also includes background-shell helpers and any tools added by your skills, MCP servers, or cloud commands.

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 approval settings, 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.

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; it updates live and does not pollute your session transcript. This is unrelated to /ultraplan and /ultrareview, which run on a cloud VM instead of locally.

Approvals

Before any action that changes your files or system, the assistant pauses and asks for approval. Read-only actions — reading files, listing directories, searching — run without prompting.

By default (--permissions auto), ordinary workspace work — reading, editing, and running commands — is allowed automatically. Shell commands run sandboxed to the workspace and temp directories with no network access; anything that needs broader access, or is classified as destructive, still asks for approval with an explicit reason.

File-editing (apply_patch) approvals keep the prompt itself compact — no inline diff — and show a v full diff hint in the footer. Press v to open the same full-screen diff viewer used elsewhere in the TUI, review every changed file, then q to return to the approval prompt and decide.

Two flags change this behavior at startup (both are global, so they also apply to cluster exec):

• cluster --plan — plan mode (see below).
• cluster --permissions full-access — skip the workspace sandbox and ordinary approval prompts entirely. Mandatory approvals and hard policy denials still apply.

Switch modes mid-session with /permissions auto, /permissions full-access, or check the current mode with /permissions (or /permissions status). Dropping back to auto stops any background shells that were started under full-access.

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, and note that it cannot be overridden by --permissions full-access.

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.

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 indicator sits at the bottom-right of the footer whenever remote control is on: yellow while connecting, green 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 yellow and then back to green, and no prompt or interrupt is replayed twice. An expired sign-in is refreshed in place.

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

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.

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.

Slash commands

Inside a session, type / to see available commands. The full set:

Next steps

• Exec & sessions — run prompts non-interactively and resume saved sessions.
• Models & configuration — switch models, set reasoning effort, and configure MCP servers and skills.
• Cloud features — /ultraplan and /ultrareview in depth.