Exec & sessions

Run Cluster Build non-interactively with `cluster exec`, and list, resume, and manage your saved sessions.

Interactive sessions are the main way to work with Cluster Build, but you can also run a single prompt non-interactively — for scripts, CI, and quick questions — and pick up any past conversation where you left off.

Run a one-shot prompt

cluster exec runs a single prompt and exits without entering the interactive UI:

cluster exec "summarize what this service does"

It reads from stdin too, so you can pipe context in. A positional prompt and piped stdin are combined (positional first, then stdin, joined by a newline):

echo "fix the failing test in api_test.go" | cluster exec
git diff | cluster exec "review this change for bugs"

Flags

Flag	Effect
`--model <id>` (`-m`)	Override the default model for this run only (not persisted)
`--effort <level>`	Reasoning effort hint — `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
`--ephemeral`	Don't save this run to `~/.cluster/sessions/`
`--resume <prefix>`	Append this turn to an existing session (see below)

cluster exec --model <model-id> --effort high "plan a refactor of the auth module"

By default (--permissions auto), exec allows ordinary workspace work and sandboxes shell commands to workspace and temp writes with no network; anything broader still prompts on stderr. For unattended runs, prefer --plan to keep the run read-only. Use --permissions full-access only in isolated, least-privilege environments — it lets the assistant run commands and edit files with no confirmation and no sandbox. It's a global flag, so cluster exec --permissions full-access "…" and cluster --permissions full-access exec "…" are equivalent.

Sessions

Every conversation — interactive or exec — is saved under ~/.cluster/sessions/ unless you pass --ephemeral. List, inspect, and delete them:

cluster sessions ls            # newest first
cluster sessions ls --here     # only sessions started in this directory
cluster sessions show <id>     # print a session's contents
cluster sessions rm <id>       # delete a session

Resume a session

Resume by its id prefix (at least 6 hex characters). This works from any directory:

cluster --resume <id-prefix>            # resume interactively
cluster exec --resume <id-prefix> "…"   # append a one-shot turn

Inside an interactive session you can also run /resume to browse and switch between saved sessions.

Next steps

Models & configuration — set a default model and reasoning effort so you don't have to pass flags every run.
Interactive sessions — the full TUI experience.