Settings

Settings is a full page, not a dialog. Open it from the gear button labeled "Settings" in the app sidebar footer; press Escape to return to the app when no dialog or menu is open. Its left sidebar lists seven sections — Providers, Integrations, Web search, Voice, Notifications, Appearance, and About, in that order — above a footer that reads motriz · v1.0.0. Providers opens by default.

Providers

"Connect the AI CLIs and API keys Motriz runs your agents with." Each supported provider is a collapsible card with a status badge — "ready" (green) or "not set up" (amber). Expanding a card shows a status detail, a setup hint when something is missing, the configuration fields, and the provider's models. Providers without credentials stay visible but cannot run until set up.

Key fields are password inputs and never echo a stored value: once a key exists, the placeholder reads "configured — enter a new key to replace". CLI path fields show auto-detected: {path} until you store an override, and saving a blank field returns to auto-detection. Each card has "Save" and, once a value is stored, "Remove". Saved values are encrypted at rest — "Keys and paths are stored encrypted in the local database." — with no macOS Keychain involvement; see Privacy and safety for how the encryption works.

For per-provider setup, models, and defaults, see Providers and models.

Integrations

"Connect the workspaces every agent can use through provider-hosted MCP tools." Five integrations are available, always in this order: Linear, Notion, Atlassian, AWS, and Stitch. All five are remote, provider-hosted MCP servers — Motriz never asks you for a Linear or Notion API token. The first four connect with OAuth in your browser; Stitch takes a Google Cloud API key. A connected card shows its workspace or account, "{N} tools available", and "Last checked" with a relative time.

The section states the trust model up front: "Authorization stays encrypted on this machine. Connected tools can read and modify data and are available to every agent and model; your provider account and workspace permissions remain the source of truth." As with providers, changes are gated during work: "Stop active agents before connecting, testing, reconnecting, or disconnecting integrations."

Connection states, per-integration details, and how agents call these tools are covered in Integrations and web search.

Web search

"Embedded metasearch every agent uses for web_search and web_fetch." Motriz ships its own metasearch — "Search runs locally against the enabled engines — no account needed." Five engines sit behind on/off switches, all enabled by default:

• DuckDuckGo, Brave Search, Bing — "Keyless scraper"
• Wikipedia — "Official API — reference results"
• Brave Search API — "Official API — requires a key"; its row appends " — inactive until a key is saved", and the key field sits inline in the row with its own "Save" and "Remove"

Under "Behavior", SafeSearch is Off, Moderate, or Strict (default Moderate), and Region is "Auto (engine default)" or one of eleven locales (default Auto). The "Test search" box ("Try a query against the enabled engines") runs a real query and reports "{N} results from {engine labels}", so you can confirm which engines are contributing. Settings are re-read on every search, so a change applies immediately — even to runs already in flight. Note that Claude Code and Codex use their own native web tools; the embedded engines back the API providers' web_search and web_fetch. Details in Integrations and web search.

Voice

"Dictate prompts with a fully local speech model. Audio never leaves this machine." The section footer repeats the guarantee: "Models are stored locally. Transcription runs entirely on this Mac." Three Whisper models are offered:

1. Download a model.

   "Download" streams the model with a progress bar and verifies its checksum before install. A successful download selects that model automatically.

2. Pick between installed models.

   Installed models show an "Installed" badge; the active one shows "Selected". Click an installed card to switch. Only one model dictates at a time.

3. Remove what you don't use.

   "Remove" deletes the model file and frees disk space. Removing the selected model falls back to Base.

Models live under ~/Library/Application Support/Motriz/voice-models/. If no model is installed yet, pressing the composer's "Dictate" button opens this section instead of recording — see Work and runs for how dictation behaves in the composer.

Notifications

"macOS notifications for agent work that finishes while you're elsewhere." Two switches, both off by default:

• "Run finished" — "A run completed". The notification reads "{thread title} is done."
• "Run failed" — "A run stopped with an error". The notification reads "{thread title} stopped with an error."

Appearance

"Theme, editor colors, and file explorer icons."

App theme

Choose Light, Dark, or System. A line below reports the result — "Currently using light mode" or "Currently using dark mode", with "(following your system)." added when System is selected. The app sidebar footer also has a quick "Toggle theme" control.

Editor theme

"Applies to the file viewer and the changes diff. The matching theme is used automatically when the app switches between light and dark." You pick one light theme and one dark theme, each with a live code preview. Light options: GitHub Light (default), VS Code Light, Solarized Light, and Motriz. Dark options: GitHub Dark (default), VS Code Dark, Dracula, Tokyo Night, Solarized Dark, and Motriz.

File explorer icons

Two choices with a live file-tree sample: Colored — "Per-filetype icons and colors" (the default) — and Monochrome — "Flat, single-color icons". This styles the Files tab of the workspace.

About

"App version and local paths." It lists:

• App — the version, as motriz v1.0.0.
• Repo roots — the folders Motriz scans for repositories (your home directory by default), or "none".
• Database — the absolute path of the local database, by default ~/Library/Application Support/Motriz/motriz.db.

Check here when repository discovery misses a repository or you need the exact version for a report — see Troubleshooting. The full on-disk storage map is in Privacy and safety.

Updates are not a settings pane

There is no update section and nothing to configure. Motriz checks https://motriz.ai/downloads/latest.json on its own (at most once per hour), and when a newer build exists a pill appears in the app sidebar footer: "Update ready (v{version}) — restart". Clicking it downloads, verifies, installs, and relaunches. While agents are running, the pill is disabled and reads "Update ready (v{version}) — stop active runs first" — an update never interrupts live work. Verification details and the full updater flow are in the Reference.