Settings

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 for details on setting up profiles.

​

Providers

Configure API keys for each AI model provider. The app supports: 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; 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 for details.

​

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 use from the profile 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.

​

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.

​

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 regardless of this setting. Dangerous commands 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 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. 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 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 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.
• 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 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 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 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 panel. With a fallback set, image attachment and draw mode stay enabled even on a non-vision model.

​

Main chat directory

Choose where the main chat 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. 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. Disabled by default.
• Enable Auto Memory — let the agent save and recall its own notes per project across sessions. See Auto 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. 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.
  • 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: