Settings reference and privacy

Open Settings with ⌘,. Search matches setting names, descriptions, and related terms, so it is usually faster than browsing every category.

How settings resolve

Many agent, profile, command, and workflow settings support three scopes:

Settings precedence Most specific value wins

01 ProjectUsed when this project defines a value Chosen first

02 WorkspaceUsed when Project is unset Next fallback

03 GlobalUsed when neither narrower scope defines a value Final fallback

If Project is unset, the app falls back to Workspace, then Global.

Choose Inherit or clear an override to resume using the broader scope. The scope selector appears only where a setting supports overrides; interface-wide options such as language or update channel remain global.

Project configuration also has two owners:

• App project settings are personal and stay in the app’s local settings.
• Repository config is versioned with the project and supplies shared setup, run, and teardown commands.

See Project config and scripts for precedence and trust boundaries.

General

General contains app-wide behavior:

• Display language.
• The current update status and release channel. Nightly is currently the only available track.
• Quit confirmation and confirmation before closing a running tab.
• Whether holding ⌘ shows number hints and whether ⌘1–9 selects tabs or worktrees.
• The Open In app list, order, and custom applications.
• Conversation-storage analysis, empty-conversation cleanup, restorable snapshots, and database compaction.
• Cleanup for bundled provider helpers and diagnostic-bundle status.

Storage maintenance describes what it will reclaim before changing local history. Review the estimate and snapshot options before deleting conversations.

Appearance

Appearance controls visual and layout defaults:

• System, Light, or Dark mode; default workspace theme; per-workspace theme customization; and Dock icon.
• Monospace, editor, terminal, right-sidebar, and chat font sizes or scales.
• Terminal font and color palette.
• Workspace-tab placement and pinned-tab style.
• Compact or Detailed left sidebar, visible-worktree limit, and sidebar commit status.
• Default right-panel layout and automatic sidebar hiding.
• Word wrap in files and diffs, plus inline live edits in Chat UI.
• Loading-indicator style.

Widths, visibility, and split ratios also persist as you use the interface. See Layout, sidebars, and PiP.

Notifications

Notifications controls both the in-app queue and macOS delivery:

• System notifications: Always, Only when unfocused, or Never.
• Whether eligible alerts can break through Focus.
• Whether opening a source tab clears its queue item.
• Timeline retention.
• Per-type delivery and sound for task completion and approval or input requests.

macOS can still block system delivery at the operating-system level. The in-app notification queue remains available independently.

Keyboard Shortcuts and Command Palette

Keyboard Shortcuts lists every configurable binding and reports conflicts. Search by command or keys before replacing a shortcut.

Command Palette controls which sources appear—commands, files, worktrees, tabs, and conversations—and whether results show breadcrumbs. Palette file results remain scoped to the active worktree. Show conversations adds full-text conversation history search, which searches every workspace rather than the active worktree.

Agents

Agents defines session defaults, provider availability, routing, and execution behavior:

• Open new agent tabs in Chat UI or Terminal.
• Choose the default provider, model, reasoning effort, and naming model.
• Enable providers and visible models; override provider commands and launch flags.
• Set branch naming rules.
• Choose permission modes and explicit bypass options. Risky bypasses show warnings because they weaken provider safeguards.
• Route fast actions such as commit and Create PR/MR separately from thorough actions such as review, conflicts, failed CI, and review feedback.
• Configure normal-click and ⌘-click dispatch as reuse/new tab, prepare/submit, or background.
• Pin a provider or model for an individual action in the advanced routing table.

The routing table applies to agent-backed actions. Direct Git and forge operations such as Push, Merge, and Ready for review do not become prompts.

Claude’s beta Compliant Claude view runs local Chat UI sessions through Claude Code’s interactive mode. If it is disabled or the workspace is remote over SSH, the app uses Claude’s noninteractive claude -p path instead. Verify the mode and account shown by the CLI before long-running work.

Profiles

Profiles separates provider accounts or environments. Claude and Codex profiles can launch with distinct config directories through CLAUDE_CONFIG_DIR and CODEX_HOME; profile launch flags and colors make those sessions recognizable.

Choose defaults per global, workspace, or project scope. A work repository can therefore use a different authenticated CLI profile from personal projects without replacing the global provider choice.

Commands

Commands has two kinds of reusable instruction:

• Custom commands add named commands for your own workflow.
• Prompt templates define built-in agent actions: inline commit, Commit & push, Commit, Create PR/MR, Resolve conflicts, Review, Fix CI, investigate merge blockers, fix comments, and fix requested changes.

Keep shared company policy at workspace scope and repository-specific commands at project scope. The app adds current worktree and forge context when the action runs.

Worktrees

Worktrees controls creation, synchronization, naming, and deletion:

• Global default root for app-created worktree directories.
• Automatic worktree naming from the first meaningful prompt.
• One-time automatic tab titles from the first meaningful prompt.
• Fast-forward clean worktree branches after fetch.
• Fast-forward the clean project default branch after fetch.
• Delete the local task branch during worktree cleanup. This is enabled by default.
• Delete local remote-tracking references during cleanup. This is disabled by default and does not delete the branch on the remote forge.

Project settings can override the worktree root and branch defaults. See Branches and targets and Worktree cleanup.

Project settings

Open a project’s … menu or select its scope in Settings. Project settings include:

• Repository root and display icon.
• Default branch for new worktrees.
• Default target branch for review and PR/MR creation.
• Project-specific worktree storage root.
• Setup, named run, teardown, pre-cleanup, and post-cleanup scripts.
• Setup behavior: automatic or manual, foreground or background, submodule initialization, output auto-clear, and .env symlinking.
• Provider, model, profile, routing, and prompt overrides.

A changed default branch or target applies to future worktrees. Existing task worktrees retain their own branch and target context.

Experimental

Experimental

Experimental features are disabled by default and may change more quickly. Open Settings → Experimental and enable a feature before using it. Enabling a feature makes its controls available; it does not create workspaces, start agents, or launch background work.

Experimental exposes features that may change more quickly or require extra setup:

• Shared Context branch groups across related repositories.
• Remote workspaces over SSH.
• Non-Git projects.
• Agent orchestration.
• Browser automation, which lets agents read and drive an in-app browser tab. Acting on a page also needs a per-workspace grant, toggled by Allow agents to control the browser in that workspace’s settings.
• Mobile session continuation through Hapi.
• Automatic Claude compaction and retry after a Chat UI context-limit failure.

Review each feature’s page before using it on important work.

Privacy model

The app is local-first. For a local workspace, repositories, paths, prompts, terminal input, credentials, and session history stay on your Mac unless a provider process sends selected prompt or code context to its own model service.

A remote SSH workspace intentionally keeps the checkout, Git operations, terminal commands, and provider process on the host you selected. The app UI, settings, and session metadata remain on your Mac. Review Remote workspaces before using a host managed by another person or organization.

The app does not proxy provider traffic or replace provider authentication. Provider CLIs and Chat UI adapters follow the selected provider’s account, privacy, retention, and billing terms.

Data excluded from app telemetry

The app does not send hostnames, usernames, working directories, project names, file paths, branch names, command input, clipboard data, code, or prompts to its telemetry service.

Anonymous telemetry

Anonymous usage telemetry measures product usage and reliability. Events use random installation and app-session identifiers plus app version, update channel, macOS version, and timestamps. Session-end events can include duration and whether the app quit cleanly.

Disable it under Settings → Privacy → Share anonymous usage data. Opting out sends one final opt-out event, stops future telemetry, and deletes the local telemetry identifiers and session-state file.

Local data and credentials

The app stores settings, workspace layouts, conversation history, indexes, caches, and runtime helpers locally. Use the built-in storage and diagnostics controls instead of editing runtime files while the app is open.

Provider credentials remain owned by each provider CLI or its selected profile directory. If authentication fails in a normal terminal, repair it with the provider’s own login flow before troubleshooting the app.