> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

> Configure providers, appearance, and agent behavior

Open settings by clicking the gear icon in the sidebar. The settings modal is organized into three tabs: **General**, **Appearance**, and **Agent**.

## General

### Account

Manage your workspace profiles and authentication status.

* View all configured profiles with their workspace names
* Switch between profiles
* Add or remove profiles
* See connection status (green/red indicator)
* Log out of the current profile

See [authentication](/ctor/guide/authentication) for details on setting up profiles.

### Providers

Configure API keys for each AI model provider. The app supports:

| Provider                              | Configuration                                                           |
| ------------------------------------- | ----------------------------------------------------------------------- |
| **Anthropic**                         | API key or OAuth (Claude Pro/Max)                                       |
| **OpenAI**                            | API key, optional base URL                                              |
| **OpenAI Codex**                      | OAuth authentication                                                    |
| **xAI**                               | API key or OAuth (SuperGrok)                                            |
| **Google**                            | API key                                                                 |
| **Google Agent Platform (Vertex AI)** | ADC / service account key / API key (Gemini only) + Project ID + Region |
| **GitHub Copilot**                    | OAuth authentication                                                    |
| **OpenCode Zen**                      | API key                                                                 |
| **OpenCode Go**                       | API key                                                                 |

Only providers with configured credentials appear in the model selector during chat.

### Anthropic

The Anthropic provider supports two authentication modes:

* **API key** — pay-per-token billing against your Anthropic console account. Enter your `sk-ant-...` key in the provider card.
* **Login with Claude** — credit-based usage that draws from your Claude Pro or Max subscription. Click **Login with Claude** to open the OAuth flow in your browser; CTOR receives the token via a local callback. An **OAuth** badge appears on the provider row while signed in.

Both credentials can coexist on the same row; OAuth takes precedence when both are present. Cancel an in-flight login from the same button, by closing the browser tab, or by closing the settings window. If the browser cannot open on the current machine, copy the displayed authorize URL to another device.

### xAI

The xAI provider supports two authentication modes:

* **API key** — pay-per-token billing against your xAI console account. Enter your `xai-...` key in the provider card.
* **Login SuperGrok** — OAuth login backed by a SuperGrok subscription. Click **Login SuperGrok** to open the authorization page in your browser; CTOR receives the token via a local callback. An **OAuth** badge appears on the provider row while signed in.

Both credentials can coexist on the same row; OAuth takes precedence when both are present. Cancel an in-flight login from the same button, by closing the browser tab, or by closing the settings window. If the browser cannot open on the current machine, copy the displayed authorize URL to another device.

### Google Agent Platform (Vertex AI)

Google renamed Vertex AI to Agent Platform; CTOR shows both names so the provider is findable by either label. Expand the provider card to configure:

* **Use default ADC** — read credentials from `~/.config/gcloud/application_default_credentials.json`. Recommended for both Claude and Gemini, and required for Claude partner models.
* **Service Account Key File** — path to a service-account JSON file; the **Browse…** button opens a file picker. Use this as an alternative to default ADC. Disabled while **Use default ADC** is on.
* **Project ID** — your Google Cloud project ID. Optional for Claude on ADC (auto-resolved from the credential's `quota_project_id`); required for Gemini and for any request that uses an API key.
* **Region** — a Vertex region like `global`, `us`, `eu`, `us-east5`, or `europe-west1`. Defaults to `global` when left blank.
* **API Key** — Gemini only. Claude partner models reject API keys and require OAuth2/IAM via ADC or a service account.

To set up ADC, run `bash <(curl -sSL https://storage.googleapis.com/cloud-samples-data/adc/setup_adc.sh)` in your terminal. API keys can be generated at the [Agent Platform Studio API keys page](https://console.cloud.google.com/agent-platform/studio/settings/api-keys); some organizations disable API-key access, in which case ADC is the only option.

### OpenAI Compatible endpoints

Add custom OpenAI-compatible API endpoints below the built-in providers. Each endpoint has its own name, base URL, API key, and model list. Click **+ Add Endpoint** to create one, then configure:

* **Endpoint Name** — a display name shown in the model selector (e.g., "Ollama")
* **Base URL** — the API endpoint URL
* **API Mode** — **Chat Completions** (default) or **Responses**; choose **Responses** for reasoning-capable models
* **API Key** — optional, depending on the provider
* **Models** — add one or more model identifiers available at this endpoint

Models from configured endpoints appear in the model selector and default model dropdown, grouped under the endpoint name.

Each model has its own **Vision**, **Reasoning**, **XHigh**, and **Max** toggles plus an optional **Context** window. **Reasoning** is available only in **Responses** API mode, and **XHigh**/**Max** only when **Reasoning** is enabled. See [supported models](/ctor/reference/models#per-model-options) for details.

<Tip>
  If no API key is set in the app, the agent falls back to `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` environment variables.
</Tip>

### Default model

Select a default model that is used for new sessions. You can override the model per session using the model selector in the input bar.

### Terminal shell

Pick the shell that [Terminal tabs](/ctor/reference/panels#terminal) use from the profile dropdown:

| Profile                | Shell                                                                                                                                                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **System default**     | `$SHELL` if set, otherwise `/bin/zsh` on macOS and `/bin/bash` on Linux. On Windows, your `COMSPEC` (typically `cmd.exe`) — `SHELL` is ignored there, because Git Bash and SSH sessions export it. |
| **Windows PowerShell** | `powershell.exe` (Windows PowerShell 5.1). Windows only.                                                                                                                                           |
| **PowerShell 7**       | `pwsh.exe`. Windows only, and only listed when `pwsh.exe` is on your PATH.                                                                                                                         |
| **WSL**                | `wsl.exe`, either the default distro or a specific one. Windows only, and only listed when at least one distro is registered. Each registered distro gets its own entry.                           |
| **Custom command**     | A free-text shell command, entered in the field below the dropdown.                                                                                                                                |

The Windows profiles are detected when Settings opens, so a newly installed PowerShell 7 or WSL distro appears after you reopen the panel. A previously saved custom shell migrates to the **Custom command** profile.

For **Custom command**:

* **Save** — enabled once the field differs from the saved value.
* **Reset** — clear a custom shell and revert to the system default. Only shown when a custom shell is saved.

CTOR doesn't check that the path exists; an invalid shell fails when a terminal starts, and the error appears in the terminal pane itself. Changing this setting only affects terminals opened afterward — already-open ones keep running under their original shell.

<Note>
  On Windows, this profile also decides which shell the agent's command tool uses — see [sandbox](/ctor/reference/sandbox#windows).
</Note>

### Updates

Check for and install app updates:

* **Check for updates** — queries the update server for the latest version
* **Download & Install** — downloads the update and restarts the app

Displays your current version and the latest available version.

## Appearance

### Theme

Choose a theme for the app:

* **System** — follows your operating system theme
* **Light** — light mode
* **Dark** — dark mode

Each option shows a miniature preview of a chat session and diff view in that theme. The theme is applied immediately.

### Accent

Choose the accent color used across the UI — buttons, focus rings, links, and the user message bubble in chat. The change is applied immediately and the theme preview swatch updates to match.

| Option                   | Swatch                 |
| ------------------------ | ---------------------- |
| **Terracotta** (default) | Warm orange `#e2924b`  |
| **Sky**                  | Cool blue `#4b8ae2`    |
| **Moss**                 | Muted green `#6aad6c`  |
| **Graphite**             | Neutral grey `#86909b` |

### Reduce motion

Minimize animations and transitions across the app. Defaults to **System**.

* **System** — follows your operating system's reduce-motion preference
* **On** — always minimizes motion, regardless of the OS setting
* **Off** — always keeps motion on, overriding the OS setting

The change is applied immediately.

### Window

Available on macOS. Lets the desktop show through the app window using native macOS vibrancy.

* **Background blur** — turns on theme-aware translucent surfaces backed by macOS vibrancy. Disabled by default.
* **Surface opacity** — slider that controls how solid app surfaces appear. Lower values show more desktop blur (**More blur**); higher values keep panels solid (**More solid**). Range 25–95%, defaults to 78%. Disabled until **Background blur** is on.

### Fonts

Customize the fonts used throughout the app:

* **UI font** — the font used for the interface (menus, labels, messages). Enter a CSS font family value.
* **Code font** — the font used for code blocks, terminal output, and diff sections. Enter a CSS font family value.

The UI font defaults to the platform-native sans-serif (SF Pro on macOS, Ubuntu/Noto Sans on Linux). The code font defaults to a cross-platform monospace stack. The input field previews your chosen font as you type.

### Language

Select the app language:

* English (US)
* Traditional Chinese (繁體中文)
* Japanese (日本語)

The **System** option follows your operating system locale.

## Agent

Configure agent behavior:

* **Auto-approve bash commands** — when enabled, full-access bash commands and trusted `bricks devtools` commands run without a confirmation prompt. When disabled (default), you must approve each command before it executes. Sandboxed commands always run within the [sandbox](/ctor/reference/sandbox) regardless of this setting. [Dangerous commands](/ctor/reference/sandbox#dangerous-command-detection) such as `sudo`, `rm -rf`, or history-rewriting `git` always prompt, even when this setting is on.
* **System notifications** — when enabled (default), CTOR posts a system notification with the OS notification sound when an agent finishes its turn, fails, or pauses for a tool approval — but only when no CTOR window is focused. Click the notification to bring CTOR to the foreground. Disable to silence all background pings.
* **Scheduled tasks** — turns [Schedule](/ctor/reference/schedule) on or off. Enabled by default; existing schedules are kept but stop firing while this is off.
* **Enable ACP** — starts a local socket server so external tools (acpx, OpenClaw) can interact with the agent over the [Agent Client Protocol](/ctor/reference/acp). Disabled by default. Toggling takes effect immediately without restarting the app.
* **Sandbox settings** — opens `sandbox.json` to customize sandbox network and filesystem permissions. See [Sandbox](/ctor/reference/sandbox) for details.
* **Hooks settings** — opens `hooks.json` to run custom commands on agent events. Per-project hooks can be placed at `.bricks/hooks.json`. See [Hooks](/ctor/reference/hooks) for details.

### CLI Agents (Preview)

* **CLI Agents** — turns on backing a chat with a local CLI coding agent (Claude Code, Codex, Pi, Cursor Agent) instead of the built-in agent. Enabled by default. See [CLI Agents](/ctor/reference/cli-agents).
* A path override for each engine (`claude`, `codex`, `pi`, `cursor-agent`) — point CTOR at a specific binary instead of the one it detects automatically. Each row shows the detected version and whether it's your system install or the one bundled with CTOR.

### Default thinking level

Select a default thinking level for new sessions. Available levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Leave empty to use **High**.

### Sub-agent default model

Select a default model for sub-agent spawning. See [sub-agents](/ctor/reference/sub-agents) for how this fits into model resolution.

### Sub-agent default thinking level

Select a default thinking level for sub-agents. Available levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Leave empty to use the model-specific default. See [sub-agents](/ctor/reference/sub-agents#thinking-level-resolution) for the full resolution order.

### Fallback vision model

Choose a vision model that stands in when your active model can't process images. Some models have no image support; when one is selected, CTOR sends each image to this fallback model, which returns a text description the active model can read. Leave it empty (**Disabled**, the default) to turn the feature off.

Only models that support image input appear in the selector. The fallback covers every image the agent would otherwise miss — your attachments, images opened with `read_file`, [simulator](/ctor/reference/simulator#agent-driven-simulator) screenshots, and images returned by MCP tools. Your original image stays in the conversation and the generated description is saved alongside it, so the same image isn't described again on later turns. The description also appears under each image in the [Messages Detail](/ctor/guide/agent-usage#inspect-the-messages) panel. With a fallback set, image attachment and [draw mode](/ctor/reference/simulator#draw-mode) stay enabled even on a non-vision model.

### Main chat directory

Choose where the [main chat](/ctor/guide/main-chat#the-main-workspace) writes projects and other artifacts. Defaults to `~/bricks-ctor`, shown as a placeholder when the field is empty.

* **Browse…** — open a directory picker; the selected path fills the textbox but is not saved until you click **Save**.
* **Save** — write the entered path. Validation runs before anything is committed:
  * Must be an absolute path (relative paths like `./work` are rejected).
  * Cannot be a filesystem root (`/`, `C:\`).
  * The parent directory must already exist — CTOR creates the leaf folder, but won't create intermediate ones.
* **Reset** — clear the saved value and fall back to `~/bricks-ctor`. Only shown when a custom path is saved.

Changes take effect without restarting the app — the main agent's tools, sandbox scope, and file mentions follow the new directory immediately. If the parent of a saved path later disappears (external disk unmounted, folder deleted), the field shows an inline error and main chat refuses to start until you pick a new location or reset.

## Advanced

* **Show Thinking Content** — display model thinking content in chat messages. Disabled by default.
* **Show Messages Button** — show the **Messages** button in the input bar; it opens the **Messages Detail** panel for inspecting and exporting the messages sent to the model. See [Inspect the messages](/ctor/guide/agent-usage#inspect-the-messages). Disabled by default.
* **Show Environment Switch** — show the environment selector on the login screen. Disabled by default.
* **Enable Background Processes** — allow the agent to spawn background child processes. Supports daemon (persistent) and long-run (completion callback) modes. Enabled by default.

### Experimental features

* **Language Server Tools** — help the agent catch TypeScript errors after each edit and jump to where types and functions are defined or used. See [Using the AI agent](/ctor/guide/agent-usage#typescript-language-server-tools). Disabled by default.
* **Enable Auto Memory** — let the agent save and recall its own notes per project across sessions. See [Auto memory](/ctor/reference/memory) for details. Disabled by default.
* **Ultra Thinking Level** — offer the **Ultra** tier in the chat thinking level picker. The agent proactively fans work out to parallel sub-agents, at the highest token usage of any tier. See [Ultra](/ctor/reference/models#ultra). Disabled by default.
  * **Ultra Parallel Agents** — how many parallel sub-agents an Ultra chat may run at once, from 1 to 8. Defaults to 3. Only shown while **Ultra Thinking Level** is on.
* **Voice Input** — dictate messages from the input bar with Apple Speech. Requires macOS 26 or newer and microphone access, so the toggle only appears on supported Macs. Disabled by default. When enabled, a microphone button is added to the input bar — see [Voice input](/ctor/guide/agent-usage#voice-input).
  * **Voice Language** — the speech-recognition language for dictation: English, Traditional Chinese, or Japanese. Defaults to the app language when not changed.

## Data storage

The app stores its data in the following locations:

| Data                     | Location                                         |
| ------------------------ | ------------------------------------------------ |
| Auth config              | `~/.bricks-cli/config.json`                      |
| App settings             | `~/.bricks-project-desktop/settings.json`        |
| Chat sessions            | `~/.bricks-project-desktop/sessions/`            |
| Global skills            | `~/.bricks-project-desktop/skills/`              |
| Project skills           | `<project>/.bricks/skills/`                      |
| MCP config               | `<project>/.mcp.json`                            |
| Sandbox config           | `~/.bricks-project-desktop/sandbox.json`         |
| Per-project sandbox mode | `~/.bricks-project-desktop/project-sandbox.json` |
| Hooks config             | `~/.bricks-project-desktop/hooks.json`           |
| Auto memory              | `~/.bricks-project-desktop/memory/`              |

<Tip>
  Set the `BRICKS_PROJECT_DESKTOP_DATA_DIR` environment variable to override the default data directory (`~/.bricks-project-desktop/`).
</Tip>