orca/docs/site/content/docs/settings.mdx

---
title: Settings reference
---

Settings are grouped into panes. Everything here is searchable with `Cmd-,` then typing a keyword. Feature pages in these docs link directly to the relevant pane.

## General

- **Orca CLI** — register the bundled command-line tool for shells and agents.
- **Updates** — check for and install updates. Modifier clicks on **Check for Updates**:

| Modifier                                               | Effect                                                                                                                                         |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Shift+click**                                        | Include the latest **RC** prerelease                                                                                                           |
| **Cmd+click** (macOS) / **Ctrl+click** (Windows/Linux) | Latest **perf**-tagged prerelease                                                                                                              |
| **Option+click** (macOS only)                          | Pick a **validated local macOS build** (compatibility-checked). Failures surface as “Could Not Use Local Build” with **Choose Another Build**. |

- **Open in menu** — choose apps on the worktree **Open in** menu. VS Code / Insiders enable **Remote SSH** open for SSH worktrees; other editors remain local-path only.
- **UI zoom** — per-install UI scale.
- **Default new-worktree name** — custom prefix or marine creatures.
- **Editor Word Wrap** — default wrap for file editors (on by default). Toggle from a file tab's **⋯** menu or `Alt+Z`. Separate from **Diff Word Wrap**.

## Appearance

- Theme, accent color, density.
- Font family for UI; editor font is opt-in (empty = follow terminal font; set a value to override file editors and diffs only).
- Editor minimap toggle.
- Status bar toggles, including **Resource Manager** (CPU/memory/sessions, daemon controls, workspace disk scans).
- **Usage percentages** — show provider limits as **% used** or **% remaining** on the status-bar roster.
- App Icon — cycle between Classic, Watercolor, and Blue for the icon shown in the Dock and window switcher.
- **Language** — primary Interface control. Switch between System (follows the OS), English, 中文（简体）, 한국어, 日本語, or Español. Settings search also matches native words for “language” (语言 / 語言 / 언어 / 言語 / Idioma) so you can find Language while the UI is still in English.

## Git

- Default base ref resolver.
- Commit signing options.
- Editor for external git tools.
- Auto-Rename Branch From Work — rename Orca-generated creature branches after an agent starts work.
- **GitHub API Budget** — remaining REST (core), Search, and GraphQL quota from the local `gh` CLI. Useful when PR checks or Tasks stop refreshing; see [Troubleshooting GitHub errors](/docs/github-errors) if the numbers look fine but GitHub still rate-limits live calls.

## Terminal

- Font, theme, cursor style, padding.
- Ghostty import.
- Warp theme import — bring in your Warp YAML themes with **Import themes from Warp** (auto-discovers Warp's themes folder per OS) or **Import from YAML** for any folder of Warp-format theme files.
- JIS Yen (¥) to Backslash (\\) for macOS Japanese keyboards.
- Windows default shell (PowerShell or CMD).
- **Allow TUI Clipboard Writes (OSC 52)** — **on by default**. Lets Zellij, tmux, Neovim, fzf, Grok (and similar) write the system clipboard over the PTY, including over SSH. Turn off if you prefer the older lockdown.

## Quick Commands

- Saved terminal commands and agent-prompt presets, scoped globally or to a project. Each row has a copy control for the command body.
- Scope filters for reviewing and editing the command list. The same list syncs to the [mobile companion](/docs/mobile).
- With remote or multi-host setups, commands are grouped by the Orca host that owns them (**Saved on**). Host ownership is separate from Global/Project scope and from where the command runs — see [Terminal → Quick Commands](/docs/terminal#quick-commands).

## Agents

- Installed agents — detected CLIs you can enable or disable.
- Enable or disable detected agents so launch menus only show the CLIs you want to use.
- Agent Permissions — choose **Yolo** for fewer CLI permission prompts, or **Manual** to keep each agent's own approval flow for agents you haven't customized.
- Claude and Codex account lists.
- Startup hooks per agent.
- **Agent status hooks** — show working / waiting / done states in Orca. Toggle takes effect without restarting the app (including the Windows WSL hook relay). CLI: `orca agent hooks on|off|status`.
- **Keep computer awake** — **On** (stay awake continuously), **Agent** (stay awake while an agent is working), or **Off**. The same control lives on the desktop status bar as **Caffeinate** (coffee icon). Hidden on paired web clients.
- **Skill freshness** — the Agents pane and skill cards still show full status. Sidebar navigation only badges skills that need action (**Update available**, **Needs attention** / review); healthy, loading, and optional not-installed rows stay quiet. Use **Update** in the dialog to refresh global skills in the background (no terminal). Progress appears on the status bar; closing the dialog does not cancel the run. See [Orca skills](/docs/cli/skills#keep-skills-up-to-date).

## Browser

- Profiles (see [Browser-use profiles](/docs/browser/profiles)).
- Default Zoom — zoom level applied to newly opened browser tabs (per-tab adjustments via Cmd-wheel are remembered separately).
- Design Mode defaults.
- Devtools opt-in.
- **Remote server workspaces** — choose **This device** to render new paired-runtime browser pages on this desktop, or **Server (streamed)** to render them on the server. Traffic always goes through the remote server, and the choice applies to new pages only. See [Per-worktree browser → Remote workspaces](/docs/browser/overview#remote-workspaces).
- **Browse through SSH workspace hosts** — send browser traffic and DNS through each workspace's SSH host. Turn it off to browse from this device instead.
- **Link Routing** — open http(s) links from the terminal, markdown, and editor in Orca's browser or the system browser. Nested **Hold Shift…** inverts that default for one click (`⇧⌘-click` / `Shift+Ctrl+click`). See [Per-worktree browser](/docs/browser/overview#link-routing).
- **Show terminal link actions** — **on by default**. A plain click on a terminal link opens a compact action popover. Turn off to require `⌘`-click / `Ctrl`-click. See [Terminal → Link actions](/docs/terminal#link-actions).
- **Default Search Engine** — used when you type non-URL text in the browser address bar or the [new-tab omnibox](/docs/model/quick-open#new-tab-omnibox).

## Artifacts

- **Orca account** — sign in (same account family as Orca Relay) to publish and manage shared files.
- **Allow publishing public artifact links** — **off by default**. Device-wide gate: when on, you, agents, and the `orca` CLI on this machine can upload HTML/Markdown and mint public view links. Turning it off does not delete existing links.
- **Show Artifacts** / sidebar shortcut — open the Artifacts list to search, preview, copy, or delete account-owned links.
- **Ask Before Deleting Artifacts** — optional confirmation before breaking a public link.
- Share from an open local HTML page or Markdown editor with **Share as artifact**, or via `orca artifacts …`. See [CLI reference → Artifacts](/docs/cli/reference#artifacts).

## Integrations

- GitHub OAuth.
- Linear API token.
- Jira — Cloud (email + API token) or self-hosted Server/Data Center (PAT or username/password). See [Jira items drawer](/docs/review/jira).
- Bitbucket Cloud — **Connect** with **Email & API token** (default) or an **Access token**. Orca verifies the credential before saving. `ORCA_BITBUCKET_*` environment variables take precedence and hide Connect / Disconnect. Saved credentials stay on this machine — on a [Remote Orca Server](/docs/remote-servers), set the env vars on the server instead. See [Hosted reviews](/docs/review/github).
- MiniMax — paste a MiniMax session cookie (from `platform.minimax.io/console/usage`) to enable local usage and rate-limit tracking for the MiniMax CLI. Optional group ID and usage models fields override the defaults picked from the cookie.
- MCP servers.

## Notifications

- Agent-finished: system, sound, chip.
- Custom desktop notification sound per category.
- PR check failures.
- Update available.

## Voice

- **Enable Voice Dictation** — requires microphone permission (macOS may open Privacy & Security).
- **Microphone** — pick which input device dictation uses. Defaults to the system mic; choose a specific device (for example a headset) when you do not want the OS default. If the chosen mic is unplugged or missing, Orca falls back to the system default and shows a non-blocking notice.
- **Dictation mode** — **Toggle** (press shortcut to start/stop) or **Hold** (hold shortcut to talk).
- **Speech Model** — download/select an on-device model, or use cloud OpenAI models after pasting an API key:
  - **Parakeet TDT v3** (recommended) — multilingual European languages, offline.
  - **Parakeet TDT v2** — English, faster.
  - **Zipformer** family — bilingual ZH+EN streaming; streaming EN/ZH; **Zipformer Streaming KO** (Korean).
  - **Paraformer Bilingual** — Chinese dialects + English.
  - **Parakeet TDT-CTC JA** — Japanese.
  - **SenseVoice** — ZH / EN / JA / KO / Cantonese with auto language detection.
  - **Whisper Tiny** — 90+ languages, lower accuracy.
  - **GPT-4o mini / GPT-4o Transcribe** — cloud; needs OpenAI key under the same pane.
- While listening, a **Listening…** pill shows a **Stop** control; in toggle mode the tooltip also shows the dictation shortcut.

## SSH

- SSH worktrees, targets, passphrases, default identity file.
- Advanced: proxy / jump host; **Reuse SSH connection for faster setup** (system OpenSSH multiplexing; default on).
- Kerberos hosts: `GSSAPIAuthentication` from OpenSSH config drives system OpenSSH auth (see [SSH worktrees](/docs/ssh)).

## Remote Orca Servers

- Pair and connect to remote Orca runtimes.
- Advertise this desktop app as a server and create revocable access links.
- Advanced default runtime selection for server-routed projects, terminals, and provider checks.

## Shortcuts

- Full keymap — every binding remappable.
- Toggle Sleeping Workspaces ships unbound; assign it here if you want a direct shortcut for the sidebar sleeping-worktree filter.
- **Toggle Workspace Board** ships unbound; assign it here to open or close the Workspace Board with one shortcut. Existing bindings for `workspace.openBoard` continue to work.
- Close all editor tabs defaults to `Cmd+Option+W` on macOS and `Ctrl+Alt+W` on Windows / Linux.
- **Tab navigation defaults (new installs):** next/previous tab **across all types** is `Cmd+Shift+]` / `Cmd+Shift+[` (Ctrl on Linux/Windows). Same-type next/previous is `Cmd+Option+]` / `Cmd+Option+[`. Previous recent tab is `Ctrl+Tab`. Existing installs keep customized overrides under `~/.orca/keybindings.json`.
- **Add Review Note** defaults to `Cmd+Shift+A` (macOS) / `Ctrl+Shift+A` (Windows / Linux); remappable.
- **Send Review Notes to Agent** ships unbound; assign it here to open the send-notes menu for the active worktree's diff notes without using the mouse.
- **Delete workspace** defaults to `Cmd+Shift+Backspace` on macOS and `Ctrl+Shift+Backspace` on Windows / Linux. Hover the sidebar workspace you mean to delete; Orca still asks for confirmation.

## Repository

- Per-repo base ref and hooks.
- Auto-run commands on worktree create.
- Repo icons for the sidebar: choose an icon, full searchable emoji picker, uploaded image, website favicon, or GitHub avatar, then pick a preset or custom hex badge color.
- Source Control AI overrides for commit messages, pull request details, and branch names.
- **Worktree Shared Paths** — gitignored paths to materialize from the primary checkout into each new worktree (APFS clone-copy on macOS when possible, otherwise symlink). Complements repo-checked-in `worktree.sharedDirectories` in `orca.yaml` and `.worktreeinclude` (see [Worktrees](/docs/model/worktrees)).

## Floating Workspace

- **Enable Floating Workspace** — global surface for terminal, browser, and markdown tabs that are **not** tied to a repo worktree.
- **Terminal Directory** — start directory for new floating terminal tabs (`~` = home).
- **Toggle Button Location** — where the floating-workspace toggle appears; the keyboard shortcut works regardless of button placement.

## Plugins (Experimental)

- **Plugin system** — Settings → Plugins. Turn the system on, then review and enable each plugin individually. Nothing runs until you consent.
- **Marketplaces** — add a git marketplace source, browse plugins, preview capabilities (panels, commands, language packs, VM recipes), install, update, or roll back.
- Plugin workers always run on this computer; SSH workspace actions still route through Orca.
- Capability and API shapes may change; treat third-party plugins as untrusted software.

## Experimental

- [Activity Page](/docs/activity) — Slack-style worktree feed for agent events.
- Compact worktree cards — hide redundant second lines in the sidebar while the layout is still experimental.
- [Agent hibernation](/docs/agents/hibernation) — pause idle background agents and auto-resume them on reopen.
- **Agent Dashboard** — kanban of Needs You / Working / Done agents (optional Idle), with search and project/workspace/PR filters; open in-window or as a pop-out. **Show idle agents** lives on the dashboard board settings control, not here. See [Agents & sessions](/docs/model/agents-sessions#agent-dashboard).
- **Chat UI** — optional chat surface on supported agent terminals. See [Chat UI](/docs/agents/native-chat).
- **Cloud VM** — show setup controls and workspace **Run on** targets for repo-owned, on-demand environments (cloud sandboxes, VMs, or local Docker). Setup guide and recipe install live under this experimental toggle. See [Ways to run Orca](/docs/ways-to-run#4-cloud-vms-per-workspace-environments).
- Features not yet stable — behavior may change.