Settings

General settings

Open the Settings window, move between its panes, save or discard changes, set appearance, terminal display, new window size and notifications, and manage external editors.

On this page

Purpose

The Settings window holds the options of the whole application. They are global. They are never per project. This chapter explains the window itself: the category list, the search field and the footer buttons. It also explains the External editors pane and four general panes: Appearance, Terminal, Workbench and Notifications. The other panes have their own chapters. They are listed at the end of "What you see".

Where to find it

Click the gear Settings button (tooltip "Settings") at the right of the top bar. See Window layout. The window opens on the Appearance pane. It floats over the application on a dark backdrop.

Some buttons open Settings on a given pane:

  • Open System check (on the "Terminal engine not available" card, and in the Getting started list) opens System check.
  • Open settings (on the card for an agent program that Orkestra cannot find) opens Engines.
  • Approval rules… (in the Approvals list of the status bar) opens Approvals.
  • Open Remote settings (in the Notifications pane) is meant to open Remote.

What you see

The window

  • Title bar — a gear icon and the title "Settings". At the right is an X button (tooltip "close settings").
  • Search settings field — at the top of the left column, with a magnifier icon. When the field has text, a small X button (tooltip "clear search") shows at its right.
  • Category list — the left column. Order: Appearance & Behavior (a group with Appearance and Terminal under it), Workbench, Notifications, Task Defaults, Helm, Engines, External editors, System check, MCP, Approvals, Diagnostics, Performance, System State, License, Remote, About. The open pane has a highlighted row. The group starts expanded. It has a small arrow at its left.
  • Breadcrumb — a line above the pane. It shows the path of the open pane, for example "Appearance & Behavior > Appearance". A top-level pane shows only its name. The parts are not links.
  • Pane — the controls of the selected category. Each group has a title. Each row has a label at the left, the control at the right, and sometimes a grey hint under it.
  • Footer — Reset (with a restore icon) at the left. At the right: Cancel, Apply, OK.

Search results. The result list replaces the category list while the field has text. A row appears when the text is in the pane name or in its parent name. Upper and lower case do not matter. The match is highlighted. A pane that sits in a group shows the group name after a dot, for example "Terminal · Appearance & Behavior".

Footer buttons

  • Reset — puts the factory value of every setting into the window. It does not save.
  • Cancel — closes the window. It saves nothing. The Esc key does the same on every pane.
  • Apply — saves your changes. The window stays open. It is grey until a value differs from the saved value.
  • OK — saves your changes and closes the window.

Appearance pane (Appearance & Behavior, then Appearance)

Group Interface

  • Reduce motion — off by default. Turn it on to reduce animations and transitions across Orkestra.
  • Show the canvas minimap — a check box, on by default. See Workbenches and the canvas.

Group Status bar usage

  • Text: "Choose which providers show their usage at the bottom left of the status bar. Values come from each provider and are read only."
  • Four check boxes. Each has the provider mark and a name: Codex, Claude Code, Cursor, Antigravity. Codex and Claude Code are on by default.
  • A note under them: "Amber from 80%, red at 100%." When no box is checked, the note is "The status bar shows no usage." See Usage limits.

Group Agent launches

  • Max concurrent agents — a number field from 1 to 50; the default is 5. It paces group and scheduled launches in batches. It does not limit a single launch or block a scheduled launch because other agents are already running.

Group Projects

  • Default project location — a text field. Its grey example text is "~/Orkestra/projects". A folder button (tooltip "Choose folder…") opens a folder picker. A Reset to default button clears the field. It is grey while no location is set.
  • When a location is set, new and cloned projects use it unless you choose another parent in the dialog. When unset, Orkestra uses ~/Orkestra/projects and creates it on first use. See Adding, creating, cloning and importing projects.

Terminal pane (Appearance & Behavior, then Terminal) — one group, Terminal

  • Font family — the font used by terminal text. The default is ui-monospace, SFMono-Regular, Menlo, Consolas, "DejaVu Sans Mono", monospace.
  • Font size — a number field from 8 to 32. The default is 13.
  • Line height — a number field from 1 to 2, in steps of 0.05. The default is 1.
  • Cursor style — three buttons: Block (default), Underline, Bar.
  • Cursor blink — a switch, on by default.
  • Modified key encoding (advanced) — choose Legacy (default) or CSI-u. Some terminal programs may ignore modified key combinations sent with CSI-u, so Legacy is the compatible choice. See Terminal windows.
  • Terminal renderer — choose DOM (default) or GPU (WebGL). DOM text stays sharp at any canvas zoom. GPU text may look soft except at 100% zoom.
  • Max accelerated terminals — from 0 to 64; the default is 8. This caps foreground terminals using GPU acceleration and applies only when Terminal renderer is GPU (WebGL).

Workbench pane — the new window size is described in Canvas windows

Group File search

  • Include excluded folders — a switch, off by default. Includes project data folders and nested projects or worktrees in file searches. Dependency, build, cache folders and external mounts remain excluded. Click Apply or OK to use the choice across all projects and retain it after restart. Cancel discards an unapplied change.

Group New window size

  • Text: "Applies to every workbench. New terminals open at the base size × the multiplier; the change affects only windows opened afterwards, never already-open windows."
  • Size multiplier — choose 1× (default), 1.25×, 1.5× or 2× for new terminal and file windows.
  • Base terminal size (px) — set the width (240–2400) and height (160–1600) for a new terminal before the multiplier. The default is 560 × 600. File windows use their own base size. Reset stages the default; Apply or OK saves it.

Group Terminals

  • Prefer scrollback-friendly TUI mode — on by default. It asks supported agents launched by Orkestra to use an inline view, which keeps the terminal scrollbar, selection and scrollback available. It overrides their full-screen preference without changing their settings files. Hand-started agents are unaffected; OpenCode and Antigravity do not support this option.

Group Source Control

  • Watch Git for changes — on by default. It refreshes Source Control and the Files tree after Git changes outside Orkestra. When off, they refresh when the window regains focus, you click Refresh, or you act in Orkestra. This also controls automatic updates to worktree unmerged counts on the task board. See Source control.

Notifications pane

Group Notifications

  • Enable notifications — on by default. Show a system notification when an agent or task needs your attention.
  • Play sound — a switch, on by default. It is grey while Enable notifications is off.
  • Note: "Notifications use your operating system's native notification and alert sound."

Group Channels

  • Telegram — off by default. Send notifications to your paired Telegram device. This is disabled when Enable notifications is off. If no device is paired, Requires pairing and Open Remote settings appear instead.

Below the groups: the Send test notification button.

Other panes

  • Task Defaults — launch values for new tasks and schedules. See Settings: task defaults and engines.
  • Helm — the assistant engine, routine model, terminal recap, memory, project access and system prompt. See Settings: Helm.
  • Engines — launchers and agent status reporting. See Settings: task defaults and engines.
  • External editors — a Detected table, Rescan, and a Chosen by you list with Remove and Choose editor…. A chosen path that Orkestra also detected on its own shows as that editor; only a path that is not an editor any more reads Not found. The chooser and Remove controls edit the Settings draft; use Apply to save or Cancel to discard.
  • System check — the readiness report for this computer and your agents. See System check.
  • MCP — auto-attach, the external server and tool lists. See Settings: MCP.
  • Approvals — when Orkestra asks before a risky action. See Approvals.
  • Diagnostics, Performance, System State, License, About — see Settings: diagnostics, performance, system state, license and about.
  • Remote — control from Telegram. See Remote control with Telegram.

How to

Open the Settings window

  1. Click the gear Settings button at the right of the top bar.

Result: the Settings window opens on Appearance, with a fresh set of values.

Find a pane with the search field

  1. Click the Search settings field.
  2. Type part of a pane name, for example "term".
  3. Click the pane in the result list.
  4. Click the X button (tooltip "clear search") to bring the full list back.

Result: the pane opens at the right and the breadcrumb shows its path.

Collapse or expand the Appearance & Behavior group

  1. Click Appearance & Behavior in the category list.

Result: Appearance and Terminal hide or show. Click the row again to reverse it.

Change a setting and save it

Before you start, open the pane that has the setting.

  1. Change a control, for example click the Reduce motion switch.
  2. Click OK.

Result: the window closes and Orkestra uses the new value. Apply saves the same way and keeps the window open.

Close Settings without saving

  1. Click Cancel.

Result: the window closes. Every change you made in it is lost. The X button of the title bar, a click on the dark backdrop and the Esc key do the same.

Reset every setting to its default

Before you start, know that Reset changes every pane, not only the open one.

  1. Click Reset in the footer.
  2. Click OK.

Result: the draft in every Settings pane returns to factory values. Click OK to save those defaults across the app. To keep your saved values, click Cancel instead.

Set the default project location

  1. Click Appearance under Appearance & Behavior.
  2. Click the folder button (tooltip "Choose folder…") in the Projects group.
  3. Choose a folder in the picker.
  4. Click OK.

Result: Create project and Clone from URL start with this folder. To go back, click Reset to default, then OK.

Change the terminal font size

  1. Click Terminal under Appearance & Behavior.
  2. Click the Font size field.
  3. Type a number from 8 to 32.
  4. Press Tab.
  5. Click OK.

Result: the terminals that are open take the new size.

Make new windows larger

  1. Click Workbench in the category list.
  2. Click 1.5× (or another button) in Size multiplier.
  3. Click OK.

Result: windows that you open afterwards are larger. Windows that are already open keep their size.

Stop the automatic Git refresh

  1. Click Workbench in the category list.
  2. Turn off Watch Git for changes in the group Source Control.
  3. Click OK.

Result: Orkestra no longer refreshes at once when Git changes outside Orkestra. Source Control still refreshes when you return to the Orkestra window, when you click Refresh, and after your own actions in Orkestra. The Git letters in the Files tree still update every 4 seconds while the window has focus. The count of unmerged commits on the task board updates when the board loads again. The setting is kept after a restart. Turn it on again to bring back the automatic refresh.

Limit how many agents start at once

  1. Click Appearance under Appearance & Behavior.
  2. Click the Max concurrent agents field.
  3. Type a number from 1 to 50.
  4. Press Tab.
  5. Click OK.

Result: a group or scheduled launch starts that many agents at a time. The rest start in later batches.

Choose or remove an external editor path

  1. Click External editors in the category list.
  2. Click Choose editor… and select an editor executable.
  3. Click Apply.

Result: The editor appears under Chosen by you and is available in project IDE fields. To remove a chosen path, click its Remove button, then click Apply. Click Cancel to discard draft changes.

Rescan installed editors

  1. Click External editors in the category list.
  2. Click Rescan in the Detection row.

Result: The detected editor list refreshes.

Turn off the notification sound

  1. Click Notifications in the category list.
  2. Click the Play sound switch.
  3. Click OK.

Result: Orkestra still shows a system notification but plays no sound.

Send a test notification

  1. Click Notifications in the category list.
  2. Click Send test notification.

Result: Orkestra raises a notification with the title "Orkestra" and the text "This is a test notification." The test follows the values you saved. Click Apply first if you changed a switch.

Turn on Telegram notifications

Before you start, pair a device in the Remote pane. See Remote control with Telegram.

  1. Click Notifications in the category list.
  2. Click the Telegram switch.
  3. Click OK.

Result: notifications also go to your paired Telegram device.

States and messages

  • No matches — no pane name fits the search text.
  • Select a category. — the pane area is empty because no known pane is selected. You do not see it in normal use.
  • Apply is grey — you have no unsaved change.
  • Play sound and Telegram are grey — Enable notifications is off.
  • Requires pairing — no device is paired. Pair one in Remote.
  • No editors found on this machine — no supported editor was detected or chosen. Rescan checks again; Choose editor… can add a supported path.
  • External editors are not available on this system. — detection and choosing are disabled on this platform.
  • Too many chosen editors (32). Remove one first. — the cap is full; Remove a chosen path before adding another.
  • Reset to default is grey — no default project location is set.
  • A red line under Default project location — Orkestra could not check the location ("Could not check the default project location."), could not open the folder picker ("The folder picker could not be opened."), or the project check gave an error text.
  • A number outside the range — when you leave the field, Orkestra changes it to the nearest limit. Text that is not a number goes back to the old value. For Base terminal size (px), both fields go back if one is not a number.
  • An empty Font family field — Orkestra puts the default list back.

Limits and tips

  • Nothing is saved until you click Apply or OK. Cancel, the X button, a click on the backdrop and Esc discard your changes. Orkestra asks no question first.
  • Reset covers every pane, not only the open one. It does not change the progress of the first-run setup. It saves nothing until you click Apply or OK.
  • Esc closes the window on every pane, like Cancel. When a question box is open inside Settings, for example Restore this version? in System State, the first Esc closes only that box and the next Esc closes Settings. No keyboard shortcut opens the window.
  • Number and text fields save their value when you leave them. Press Tab or click another control. In Font family, Enter works too.
  • Outside changes. When another part of Orkestra or an agent changes a setting while the window is open, a field you did not edit shows the new value. A field you edited keeps your edit.
  • Search finds pane names only. It does not search the labels inside the panes.
  • The window always opens on Appearance with the group expanded. A button that names a pane (see "Where to find it") opens that pane.
  • Typography. After you save, open terminals take the new font family, size, line height and cursor values. Scrollback limits and the history cap are in Performance. See Settings: diagnostics, performance, system state, license and about.
  • Telegram notifications also need Enable remote control to be on in Remote and a paired device. The Telegram switch alone is not enough.
  • Group and scheduled launches. Max concurrent agents paces them. It does not limit a single launch. See Scheduler and routines and Starting terminals and agents.