# Overview



Cluster Build is a terminal AI coding assistant. You chat with a frontier model
of your choice, and it can read and edit files in your project, run shell
commands, and search your codebase, all from one command: `cluster`.

It talks to Clusterbase's hosted agent gateway, so there are no API keys to manage: you
sign in with your [Cluster](https://cluster.app) account and start working.
Everything it stores — config, sessions, and your sign-in — lives under
`~/.cluster/`.

Most of the time Cluster Build runs **locally** in your terminal. When a task is
bigger than one machine, it also reaches into the **cloud**: `/megaplan` plans
against your repos on a remote VM, and `/megareview` runs a fleet of review agents
over your changes. See [Cloud features](/docs/build/cloud).

## Install [#install]

```bash
curl -fsSL https://assets.cluster.app/serve/cstatic-assets/releases/cli/install.sh | sh
```

This installs the `cluster` binary to a user-writable directory on your `PATH`
(typically `~/.local/bin`) so it can keep itself up to date; set `INSTALL_DIR` to
choose another location. Confirm it's on your `PATH`:

```bash
cluster --version
```

Then sign in:

```bash
cluster login
```

The [quickstart](/docs/build/quickstart) walks through your first session
end-to-end.

## What the assistant can do [#what-the-assistant-can-do]

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

* **Run shell commands** — including long-running background processes
* **Read files** — by line range, byte range, or surrounding code block
* **View images** — inspect local PNG, JPEG, GIF, or WebP files as model-visible media
* **Search** — list directories, find files by name or path, and grep across your codebase
* **Edit files** — apply patches and write changes
* **Track a plan** — for substantial work with multiple steps or dependencies, or when you ask for a checklist, maintain a visible task list that updates as steps move from pending to in progress to complete

The first time you use it in a directory, Cluster asks you to trust that
workspace; once trusted, tools run with your normal OS permissions — no sandbox,
no per-call approval. See [Interactive sessions](/docs/build/interactive) for
workspace trust, plan mode, and the full slash-command reference.

## Where things live [#where-things-live]

Everything Cluster Build stores is under `~/.cluster/`:

| Path          | Contents                                          |
| ------------- | ------------------------------------------------- |
| `config.toml` | Your settings — model, reasoning effort, and more |
| `auth.json`   | Your sign-in token (created by `cluster login`)   |
| `sessions/`   | Saved conversations you can resume                |
| `skills/`     | Your custom skills                                |
| `commands/`   | Your custom slash commands                        |

## Next steps [#next-steps]

* **[Quickstart](/docs/build/quickstart)** — install, log in, and run your first task.
* **[Interactive sessions](/docs/build/interactive)** — the TUI, tools, workspace trust,
  plan mode, and slash commands.
* **[Exec & sessions](/docs/build/exec)** — run prompts non-interactively and manage
  saved sessions.
* **[Config basics](/docs/build/config/basic)** — pick a model, set
  reasoning effort, and tune `config.toml`.
* **[Cloud features](/docs/build/cloud)** — remote planning with `/megaplan` and
  cloud code review with `/megareview`.