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.

On the Build daemon

Sessions on the Build daemon — including the terminal's own sessions and ones opened from other devices — can spawn and message local agents too. Children use the session's tools and MCP servers, ask whoever is watching the session for approval, and anything they send to root reaches your next turn. The agent panel on every watching client shows the agents a session spawned and the messages they sent you, and a client that starts watching is caught up.

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

Where sessions run

cluster opens its session on the Build daemon — the one Build server per ~/.cluster that every local client shares — and starts the daemon in the background when none is running. Because the session lives on the daemon, other clients can watch it live, and a turn keeps running after you close the terminal; resuming the session shows it.

The startup banner says where sessions run, on the line under the model:

Cluster Build v0.1.71
kimi-k3 with high effort · Cluster Max
Remote control on · gpuserver

When sessions run on the daemon it shows remote control's live state — on · <name>, connecting · <name>, stopped · <name>, sign-in needed · <name>, removed · <name>, or off · /remote on — and it reads This terminal only when every session stays in the terminal. /status names the connection — Build daemon v<version>, or this terminal only (<why>) — and has a Remote control row.

The daemon takes sessions in your home folder and in every folder you have trusted (the trust prompt, or cluster trust add); trusting a folder takes effect without restarting it. A session stays in the terminal, with a notice saying why and how to fix it, when its folder is neither, the daemon cannot start, an outdated daemon still has work running, or with --no-memory or computer use kept to the terminal. To keep every session in the terminal, start with:

cluster --no-daemon

Remote control

Remote control belongs to the daemon, not to the TUI: once it is on, every session on the daemon is live on your other signed-in devices with no further step. Turn it on with one command:

cluster remote-control on

It signs you in if your sign-in is missing or predates remote control, applies the setting to the running daemon (starting it if none runs) and waits until the relay connects:

Remote control is on as "gpuserver". Your other devices can reach this machine.

If it cannot connect it says why in a sentence and exits non-zero. --name sets what your other devices show for this machine (default: the hostname the first time, then the saved name).

cluster remote-control status   # connected, connecting, stopped (and why), sign-in needed, removed or off
cluster remote-control off      # disconnects at once; keeps this machine's identity

Turning it on again after off reconnects the same machine rather than adding another to your list. In the terminal, /remote on and /remote off do the same without blocking the chat (Esc stops waiting), and /remote says where the current session runs and remote control's state. Approvals that only you may give, such as plugin installations, are asked only in local interactive clients, never on a relayed device.

The Build daemon

cluster app-server daemon start    # detached; prints its pid and socket
cluster app-server daemon status
cluster app-server daemon stop     # stops every session it runs

daemon stop also keeps running terminals from starting it again — their sessions continue in the terminal, with a notice — until daemon start or a new cluster clears it. A daemon the terminal starts runs in your home folder with that terminal's environment (variables like PATH that its tools need) until it restarts. To limit the daemon to specific folders instead of home and trusted folders, set allowed_roots in ~/.cluster/config.toml:

[app_server]
allowed_roots = ["/Users/me/code"]

A remote device can also start a session without choosing a folder ("Start from scratch"). The daemon creates a new empty folder for it under ~/.cluster/scratch/, even when allowed_roots doesn't include that path.

Stage Manager

Stage Manager lists your saved and live sessions so you can inspect and switch among them without stopping running work. Open it with /stage, or press ← with an empty composer; Esc or → returns to the conversation.

• Press g to group sessions by project, status, or model. Groups show counts.
• Press Tab to filter by status: all, needs input, working, ready, or inactive.
• Closed conversations stay listed as Inactive; opening one resumes it in its saved folder. Select Show more to load older history.
• Wide terminals show a details pane beside the table.

Switching sessions preserves your draft, queued input, and pending questions. Stage lists your account's sessions on the connected Build daemon, or on this terminal's own session server when sessions run only here.

Fast mode

/fast switches the model between standard and Fast service tiers. Fast costs more and responds faster: GPT-6 Astra, GPT-6.1 Sol, GPT-6 Luna, and Kimi K3 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.

While queued, the input shows what's holding up delivery — waiting for model response, or waiting for N tool(s) for tool calls still in flight — so you can tell at a glance why it hasn't gone out yet.

Queued follow-ups are handed over one at a time, in order, at each of these boundaries. A queued ! shell command 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.

Press ↑ on an empty composer to move the newest editable queued follow-up back into the composer without cancelling the running turn or pausing the queue; Enter re-queues your edit. On a queue paused by Esc, it works the same and the queue resumes once it is empty. With a draft in the composer, ↑ keeps its usual cursor/history behavior, and with nothing queued it walks history. A ↑ edit last queued hint appears whenever a queued item can be recalled (generated plan, picker, and notification items can't).

Suggested follow-ups

Build can suggest one next message after a successful interactive turn. It is off by default; turn it on with:

cluster config set prompt_suggestions true

The suggestion appears as a single line of dim text in the empty composer, with an ellipsis if it is truncated. Tab copies the full suggestion into the editable draft, and a separate Enter sends it. Esc dismisses the suggestion or cancels it while it is being generated. Typing, pasting, or adding attachments takes precedence, and a suggestion is never sent automatically.

Suggestions aren't added to the conversation, and aren't offered in cluster exec, for replayed history, or after a failed or cancelled turn. Turn them off with cluster config set prompt_suggestions false.

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.

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.

Tool results stay compact in the chat viewport — at most two visible (wrapped) rows of raw output, followed by a width-aware "… +N lines (ctrl + t to view transcript)" hint when more was produced — while the pager (Ctrl-T) shows the fuller retained output, including after resuming a session. This applies to shell calls, ! user shell commands, background process control results (wait, input, and stop), native tool errors, and MCP, browser, and computer-use results. 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.
• Status line — configure the footer's fields with /statusline.
• Config basics — switch models, set reasoning effort, and configure MCP servers and skills.
• Cloud features — /megaplan and /megareview in depth.