Settings

Ovvi ▸ Settings… (⌘,) opens the Settings window (D106). It looks like macOS System Settings: a sidebar of pages on the left, and the page on the right as a grouped form. A row in a list (a machine, a plugin) opens a page of its own, with a Back button. A change takes effect at once. There is no Save button, except on a machine's page.

Each setting is one key in app storage (UserDefaults), per device (Data), unless the table says otherwise. Settings that are not on this page do not exist.

The window

• Size. 715 × 560 pt when it opens, as System Settings. The width stays; the height changes with the window's edge, down to 400 pt. The sidebar is 215 pt wide and always shows.
• Chrome. A window with a toolbar, so the system draws it as System Settings: the sidebar floats inside the window with the traffic lights at its top, and the toolbar shows the page's title and, on a machine's or a plugin's page, the Back button.
• Sidebar. General, Appearance, Terminal, Agents, Keyboard Shortcuts, Machines, Plugins and Privacy, each with its filled two-tone symbol (13 pt medium) on the same 22 pt rounded tile, as Raycast's settings: in dark a dark grey tile lit from the top with a fine light rim and a near-white symbol, in light a white tile with a fine dark rim and a dark grey symbol. The same grey tile for every page, never a colored one, reads as one set, and a selected row leaves it as it is. The first row sits 6 pt lower than the system puts it under the search field. Every page always shows, Privacy too.
• Controls. Each row has its title on the left and its control on the right. A row's value field is the form's own: no border, its text on the right, 220 pt wide, with a word in it while it is empty (Required, Optional). A field among other controls (an agent's extra arguments, the plugin source) has a border. Buttons in a section's header are small.
• A machine's or a plugin's page follows System Settings' detail pages: a header card with a large icon, the name and a line or two of state, then the sections, and the action that removes it last, in a section of its own.
• Search. The field at the top of the sidebar. While you type, the sidebar lists the settings whose title or other words hold every word you typed, each with its page, or No Results. A pick opens the page, scrolls to the row and rings it for one second.
• Opening at a page. Ovvi ▸ Plugins… opens the Plugins page.

General

Open at login: macOS opens Ovvi when you log in, as any launch. The switch reads the system each time Ovvi comes forward, so a change in System Settings ▸ General ▸ Login Items shows here. When macOS waits for you to allow it, the switch says so and Open Login Items opens that page. A run with a config folder of its own (the UI tests) only flips the switch.

New panes open: what every new pane opens. New Pane shows the chooser (New pane). Its line under the title says "What ⌘T, ⌘D and New Space open." for New Pane (with the keys that New Tab and Split Right have), else "Hold ⌥ as you make a pane to choose each time." Any other choice opens that kind at once, with no chooser (A fixed pick). The key holds the row's id: terminal, the agent's command, or the plugin's id. The list has every agent and every plugin with a chooser row, also one whose Show in New Pane switch is off. A picked plugin that is gone counts as New Pane, and the pop-up shows New Pane.

Focus follows mouse: a card gets the keyboard when the pointer rests on it for 0.15 s, only in the key window (Moving the keyboard).

Balance splits automatically: its line under the title says "Panes side by side or stacked keep equal sizes as panes open and close." On, each pane that opens or closes evens out the panes in its row or column. Off, the app never evens them by itself: a split halves the pane, and a closed pane's neighbor takes its place, as in herdr's own window. Balance Splits (⌥⌘=) works either way (Layout).

Appearance

• Appearance and interface style: Theme and accessibility.
• The text size is the terminal font size. A change applies to every terminal at once, without opening its stream again. Each card's grid changes, so the PTYs resize.

Terminal

Every setting here applies to every terminal at once, as the text size does, without opening a stream again. So the page has no preview.

• Font: JetBrains Mono is the font that libghostty carries, so it works on a Mac that does not have it installed, as in Ghostty. SF Mono is the Mac's own monospaced font. Each shows once, also when the Mac has a copy installed.
• Cursor: a program that asks for its own shape gets it, for example vim's bar in insert mode. herdr's frames carry the request.
• Blink the cursor: on, the cursor blinks unless a program asks for a steady one. Off, the cursor stays still unless a program asks for a blinking one.
• Option key: with Types special characters, ⌥B types ∫. With Acts as Meta, ⌥B sends Esc B, which shells and editors read as Meta-B. Left acts as Meta does this only for the left Option key. ⌥← and ⌥→ move by word with every choice.
• Copy text when you select it: a selection goes to the clipboard as you make it.
• The colors follow the appearance: Alabaster in light, Afterglow in dark.

Agents

• Open new agents in: what the card of an agent that New Pane or Start Agent Here starts shows first. The header's Chat | TUI switch changes it later (Chat view).
• Sort spaces: the order of every session's sidebar until that session's own Sort Spaces menu picks (Sort Spaces).
• Show closed sessions: the sidebar's Archived Sessions, which lists the sessions of Claude Code, Codex, Pi and OpenCode that no pane runs. Off, the shelf hides and the app reads nothing (Archived Sessions).
• Agents in New Pane lists Claude Code, Codex, Pi and OpenCode, each with its program tile, its command and two controls:
  • The extra arguments go into the agent's typed line right after its command, before Ovvi's own flags: claude --model opus …. The field refuses a line break, a quote and a backslash, as the hooks do (D76). If the agent does not start, the second try types the command alone (New pane). Relaunch with Chat adds them too, and has no second try.
  • An agent that is off has no row under Agent in New Pane. Its command goes into hideInNewPane, the list that hides plugins too, so a plugin whose id is an agent's command goes with it. With all four off, New Pane has no Agent row.
• The notification switches (D105). Needs you and finishes turn off the app's own banners for those changes. When an agent sends one turns off the banners that agents send with ovvi notify, which then answers "notified": false (Notifications). In the palette, each has a command whose title says what a pick does, for example "Turn Off Notifications When an Agent Needs You" (D48). Notification Settings… opens Ovvi's page in System Settings, where banners, sounds and the Dock badge are.

Keyboard Shortcuts

Every action that has a key, or can have one, in one list: the app's and each plugin's, third-party plugins too. A key that the user sets here is the key everywhere: the menu bar, the palette (⌘K), the Keyboard Shortcuts panel (⌘/), the tooltips and the text that names a key.

• Top row. A search field and Reset All. The search keeps the actions whose title, group or keys hold every word typed (tab, ⌘T, cmd+t), or shows No Results.
• Groups. App, Sessions, Spaces, Tabs, Panes, Terminal, Edit, Browser and Plugins (what works over any plugin card: Back, Forward, Reload Plugin), then one group per plugin with keys, named as the plugin. Each row is the action's title and its keys as keycaps, or None.
• Recording. A click on the keys asks for new ones: the field says Type Shortcut. The next key with ⌘, ⌃ or ⌥ becomes the action's only key. ⎋ cancels, ⌫ clears the key, a click anywhere (the field too) only cancels, and a key with no ⌘, ⌃ or ⌥ beeps and waits. Keys the app uses (⌘W, ⌘,) record too.
• Conflicts. A key another action already has where this one works asks under the row: "⌥⌘Y is New Space's key." with Cancel and Swap. Swap gives the other action this one's old key. Two actions only conflict where both work: a browser's ⌘R and a terminal's ⌥⌘R never meet, and neither do two plugins' keys. So each such action has its key only where it works: Reload Page only over a browser card, Insert Path only over a terminal, as Save and Find Previous only over an editor. macOS's own keys (⌘Q, ⌘H, ⌥⌘H, ⌘M, ⌘Z, ⇧⌘Z, ⌘X, ⌘C, ⌘V, ⌘A, ⌃⌘F, ⌘`, ⌃⌘Space) are never an action's: the question has Cancel only. A row whose key another action holds (a plugin's key that the app uses) shows a warning symbol that names the other action; the app's action keeps the key.
• Reset. A changed row shows a reset button that gives back its default keys. Reset All gives back every default.
• Saved in settings.json under keys, the chords per action id, for example "keys": { "tab.new": ["option+cmd+y"] }; an empty list is no key. An action with no entry has its default keys (Keyboard shortcuts).
• With no main window in front (Settings, About), Close Pane's key closes the window. Back and Forward work over a plugin card with history; elsewhere the page keeps the keys.
• Keys that belong to a control are not in the list and stay fixed: ↩, ⎋, ⇥, arrows and typing in a list, a field, the chooser or a dialog; Return and ⇧Return in a chat's composer, Esc to stop the agent; Esc to leave the overview; and a plugin page's own keys inside its lists (a Git diff's [ and ]).

Machines

This Mac, then each remote machine, in the machine menu's order. Each row shows the machine's icon, name and SSH target (This Mac: the Mac's own name), and for a remote machine Connected (a window of it is connected) or Not connected. Add Machine… opens an empty machine page.

A machine's page:

• The header: the machine's icon and name, and Connected or Not connected (This Mac: its own name).
• Connection: Name, SSH target and Icon (Add a machine). Under them, a target with a space or a leading - says so in red, and Save. Save keeps an edit. On Add Machine's page the buttons are Cancel and Add: Add saves the machine, opens it in a new window and closes Settings. Return is Save or Add, Esc is Cancel.
• Browser: Website data, Clear… removes the logins, storage and cache of the machine's browser cards, and its approved websites, after a confirmation. This Mac's page has the header and this row.
• Remove ‹machine›: Remove…, last, takes the machine off the list after a confirmation. Its terminals keep running on the machine.

Plugins

The install field with Install, New Plugin… and Reload All, then every plugin: the browser first, then the plugins that come with Ovvi, then yours. Each row shows the plugin's icon, name, version and source. A row opens the plugin's page:

• The header: the icon, name, version, description and source, and on its right Update (Install when its package did not load), Update to Version ‹x› or Reset to Default when offered, and Show Log and Reload for a plugin with code (not the browser).
• Settings that the plugin declares in its manifest (Settings), then Show in New Pane. A plugin's cards read them and hear each change (The plugin API). New cards start with them; a card keeps its own choice once you change it in its header. They are in settings.json under plugins, one value for every machine.
• Remove ‹plugin›: Remove…, last, for a plugin that is not Ovvi's own.

The browser's page has its network choice for new cards on a remote machine, Show in New Pane, and a link to its approved websites on the Privacy page. How it works: The Plugins page.

Privacy

The websites that each machine's browser cards load by themselves, one section per machine (When a page loads by itself). Each section lists its sites, each with Remove, or says No approved websites; Clear All is in its header while it has any. Under the list, a field and Add approve a site before any card opens it: the address becomes its origin, as a page you open is approved (https when you type no scheme, http for localhost, 127.0.0.1 and a .localhost name). An address that is not a web address leaves Add off. A machine keeps its newest 200.

In the menu bar

The menu bar keeps the quick switches. Each also is a command in the palette, with a title that says what a pick does (D48).

Fixed values

What the notifications do: Agents and notifications.