Orca

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. Update Delay waits None (the default), 1, 3, 7, 14, or 30 days after a release is published before offering it. A held update shows when it becomes available; choose Skip Delay Once to check without waiting. With a 14- or 30-day delay, a release may leave the feed before it becomes eligible. Modifier clicks on Check for Updates:
ModifierEffect
Shift+clickInclude 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.
  • Format on Save — off by default. Enable it and configure a formatter and include patterns for each project. See Monaco editor → Format on save.
  • Default Markdown view — choose how Markdown files open. See Rich markdown editor.
  • Insert Final Newline — optionally add a final newline when saving files.
  • 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.
  • Reuse a preview tab when browsing files — on by default. Turn it off to open each single-clicked file in its own tab instead of replacing the current preview tab.
  • Collapse Unchanged Regions — fold long unchanged bands in single-file diffs while keeping a little surrounding context visible. Expand a band when you need the full file; View all changes keeps its own collapsed layout.

Appearance

  • Theme, accent color, density. Search the theme pickers by name. Installed plugins can add app and terminal themes to the theme pickers; an app theme may offer its terminal colors too.
  • 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; when your projects live on a paired Orca server, it lists that server's processes under the server's name).
  • Usage percentages — show provider limits as % used or % remaining on the status-bar roster. The roster now defaults to a shorter Compact view unless you already chose one; Detailed is still available from the same selector.
  • 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, 中文（简体）, 繁體中文, 한국어, 日本語, Español, Deutsch, Русский, or Türkçe. Settings search also matches native words for “language” (语言 / 語言 / 언어 / 言語 / Idioma) so you can find Language while the UI is still in English.

Chat

Choose the default Chat or CLI launch surface and per-agent overrides here or under Agents. New installs default to Terminal; existing launch preferences are preserved. See Chat UI.

  • Behavior — choose whether follow-ups queue, whether sending moves the scroll position, when idle chat agents stop, whether working chats resume after a restart, and whether a usage-limited chat continues automatically after its limit resets. Set permission defaults for new sessions under Agents; an existing chat keeps its own mode.
  • Agents — choose Chat or CLI for each supported agent. Choices apply to starts from this desktop, including CLI, orchestration, and relayed phone launches. If Antigravity’s chat runtime is not installed, its row offers Install; Remove stops its running chats and removes the runtime while keeping chat history.
  • Appearance — choose a chat Font family (with a preview and suggestions from installed fonts), Text size and Code text size in pixels, Width, and Contrast. Turn on Match terminal interface to use your terminal's font and colors for the whole chat, and stay in sync if you change your terminal theme later; the font and size controls are disabled while it is on. Reset chat appearance restores the defaults.
  • Inline visuals — let the agent show charts, diagrams, and mockups inside its replies. Applies to newly started chats.
  • Chat naming — new chats use their own agent and account to generate a name by default. Choose a different naming agent under Advanced; previously saved naming commands and arguments continue to work.

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 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.
  • Default shell for new local terminal tabs. Leave it blank to use the system default; Windows also offers PowerShell, Command Prompt, and WSL when available.
  • Shell arguments for a custom Unix default shell, under Default shell → Advanced. Choose -l (default) for a login shell, or Custom args and enter one argument per line. An empty custom list passes no arguments.
  • Running terminal limit — set a limit per computer under Advanced. The default is half the system terminal limit, up to 4096, or 256 when Orca cannot read the system limit. Changing it does not close running terminals. After updating, open a new terminal to use the new terminal host; older remote servers must update before their limit can be changed.
  • 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.
  • 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.

Agents

  • Installed agents — detected CLIs you can enable or disable.
  • Per-agent launch defaults — override an agent's binary path or name, and edit its default Command and Arguments (and environment). Structured native chats use the same saved command and arguments. These launch settings are edited on the workspace's own host, so a remote or SSH workspace uses the settings from the machine that runs it.
  • Enable or disable detected agents so launch menus only show the CLIs you want to use.
  • Agent permissions — choose Manual, Auto, or Yolo for new terminal and structured-chat sessions. Auto lets supported agents (Claude, Claude Agent Teams, and Codex) approve routine actions themselves; when you choose it, use Other agents to set Manual or Yolo for agents that do not support Auto. Existing chats keep their current mode, and agents with custom launch arguments remain unchanged until you replace those arguments with a preset.
  • Folder trust — the first time you start an agent in a new repository, choose whether Orca trusts the repository for agents or lets each agent ask for itself. Repositories you already use keep their previous behavior. You can change the choice in the repository settings. See Codex in Orca and Supported agents.
  • Share Codex history across accounts — on by default. History from Orca-managed accounts also appears in ~/.codex when you switch back to system default. Turning it off stops new sharing without removing existing history. Older SSH or WSL hosts need an update before this setting is available there.
  • Run each Codex terminal on its own server — on by default. Keeps Orca's status and tab-closing correct for Codex tabs; turn it off to use Codex's shared server and its agents overview. Applies to new terminals. A companion Warn when a Codex tab shares a server notice appears when a Codex you started yourself shares a server. See Codex in Orca.
  • Account lists for Claude, Codex, OpenCode, Devin, Antigravity, and the GLM Coding Plan. On Linux, a saved credential that could not be encrypted is flagged here with a warning. Each Claude account keeps its own config folder, and adding one offers Copy sign-in link instead when your default browser is already signed in to another Claude email. The Antigravity account row also shows its chat runtime's install status and lets you install or remove it for that host.
  • OpenCode Go session cookie — paste the full opencode.ai Cookie header, including __Host-console_session, to show Go rate limits. An auth cookie alone is insufficient.
  • 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.

Browser

  • Profiles (see Browser-use profiles).
  • Password manager — enable saved logins, manage or import them; see Password manager.
  • 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.
  • 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.
  • Terminal URL clicks — choose whether a plain URL click opens the action menu, opens directly, or requires a modifier; configure middle-click URL behavior separately.
  • 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.
  • Default Search Engine — used when you type non-URL text in the browser address bar or the 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 up to 10 MiB 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.

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.
  • 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, set the env vars on the server instead. See Hosted reviews.
  • 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. Repository MCP settings stay with the host you selected them on.

Notifications

  • Agent-finished: system, sound, chip.
  • Custom desktop notification sound per category.
  • Machines — choose which machines can show notifications on this computer (this computer, SSH targets, paired Orca Servers). A paired server's switch also covers work reached through it; a newly added machine still notifies. See Notifications & Inbox.
  • PR check failures.
  • Update available.

Voice

  • Set up — when no usable model is selected, Voice suggests an on-device model for your language. Set up selects and downloads it, requests microphone access, and enables dictation. You can choose another model from the list. Existing local model downloads may need an update; start it from Voice settings or the dictation pill before relying on offline dictation.
  • 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), Hold (hold shortcut to talk), or Auto (hold to talk or tap to toggle).
  • Dictation language — choose the language used by Whisper, SenseVoice, and OpenAI dictation models.
  • 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 ZH; Zipformer Streaming KO (Korean). Zipformer Streaming EN is no longer offered; existing selections move to Parakeet v2, which you may need to download.
    • 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 Transcribe — cloud; needs an OpenAI key under the same pane. Saved GPT-4o Transcribe selections move to GPT Transcribe.
  • You can also configure an OpenAI-compatible transcription service, choose whether to use the GPU for on-device models, add personal or repository vocabulary, and remove filler words.
  • With voice enabled, Orca loads the on-device speech model ahead of your first dictation. Use Unload Speech Model to choose when to free that memory. Desktop dictation stops after a minute of silence and keeps the text captured so far.
  • The dictation pill shows committed and pending words and lets you finish or cancel. On-device dictation inserts phrases as you pause. If transcription fails, you can retry the recording. Pressing Enter or Send while dictating waits for the words before sending. You can also dictate into a focused field in the browser using Toggle or Auto mode; Hold mode cannot detect key release inside a page.

SSH

  • SSH worktrees, targets, passphrases, default identity file, and bulk host management. Select several hosts to Test or Remove them together; hosts removed from the OpenSSH-config list stay removed until you choose Restore removed hosts.
  • Advanced: proxy / jump host; Reuse SSH connection for faster setup (system OpenSSH multiplexing; default on); per-host Allow this host's orca CLI to control Orca.
  • Managed servers — Orca installs and runs its own server on an empty SSH host and keeps it up to date; view its version and terminals, Update, Roll back, Recover, or Stop… / Forget… each one. Every SSH host runs on this managed server — the old Runtime selector is gone, and a host it cannot run on shows the reason and does not connect. See SSH worktrees → Managed Orca server.
  • Kerberos hosts: GSSAPIAuthentication from OpenSSH config drives system OpenSSH auth (see SSH worktrees).

Remote Orca Servers

  • Pair and connect to remote Orca runtimes in one server list. Use Add server to paste an access link, install on an SSH host, or set up a Cloud VM; each row shows its status and puts less-common actions in its ⋯ menu.
  • Advertise this desktop app as a server and create revocable access links.
  • Set this desktop's Machine name for paired mobile hosts; leave it blank to use the detected computer name. See Mobile companion.
  • 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 Child Workspaces ships unbound; assign it here to show or hide a parent worktree's nested children, the same as clicking its N children chip. It targets the worktree under the pointer, or the active worktree when nothing is hovered.
  • 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. See AI action recipes.
  • 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).

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

  • Open Settings → Plugins, use the status bar button, or press Cmd-Shift-X / Ctrl-Shift-X outside text fields. Browse the catalog, filter by category or install state, and enable or disable installed plugins.
  • Plugins can add themes, icon themes, syntax highlighting, custom editors, and other capabilities. You can also add a git marketplace source and manage installed versions.
  • The plugin system is on by default. Installing a plugin, including through an orca://plugins link, opens a review screen. Plugins that run code require your consent before installation and, once approved, have full access to your computer. Install only plugins you trust. Plugin workers run on this computer; SSH workspace actions still route through Orca.

Experimental

  • Activity Page — 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 — 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.
  • Browser extensions — enable Chrome Web Store extensions in local browser profiles after a restart. See Per-worktree browser → Chrome extensions.
  • 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.
  • Features not yet stable — behavior may change.