New pane

A new pane asks what it runs: Terminal, Agent, Browser, File Explorer, Git, or another plugin whose manifest has a chooser row (How it shows). Terminal is selected, so ⌘T and then Return gives a terminal with no click. Settings ▸ General ▸ New panes open can make every new pane open one kind instead (A fixed pick).

Which panes show it

• Every pane the app creates with a new shell: ⌘T and the title row's +, ⌘D, ⇧⌘D, Split Left and Split Up, ⌃⌘T and every New Space (the page header's +, the space menu, a folder dropped on the Dock icon), New Tab in a space's menu, and the first space of a session the app started.
• The herdr pane and its shell start at once behind the chooser. Nothing in herdr waits for the pick.
• Panes made outside the app (herdr's TUI, its CLI, another device) and panes that already run something show their terminal. A moved pane (Move Pane to Tab, a drag) keeps what it shows: the chooser follows its pane by terminal id.
• Replace Pane (⇧⌘R) on a terminal gives a fresh shell with no chooser. On an agent, browser or plugin pane it gives a fresh shell with the chooser.
• The chooser is the app's own state, kept on the session's HostStore, so every window of the app shows it on that pane. herdr, its TUI and other devices see a plain shell. After a relaunch, a pane still at the chooser shows its terminal.
• The chooser leaves without a pick when the pane starts to run something else (a program other than the shell, or an agent that herdr reports), for example when someone types into it from herdr's TUI. Then the terminal shows.

A fixed pick

Settings ▸ General ▸ New panes open is New Pane by default: the chooser shows. When it names a kind (Terminal, an agent, Browser, File Explorer, Git or another plugin with a chooser row), each pane in Which panes show it makes that pick at once, in the same frame the card shows. The list never shows.

• The pick is the chooser's own: Terminal shows the shell, an agent shows its loader and starts as in Agent, and a plugin shows its loader and takes the pane's place as in Browser. It starts in the folder herdr starts the pane in. A pick that waits for herdr's pane (an agent, a plugin) shows its loader on the new card meanwhile.
• The chooser on demand. Hold ⌥ while you click to make the pane: a +, a split button in a card's header, or a menu item. Then the chooser shows as usual. The app reads ⌥ as it makes the pane, before it asks herdr.
• ⌥ in the menus. With a fixed pick, the four splits (View ▸ Pane and the card's menu) and File ▸ New Space have an alternate item that shows while ⌥ is held, as macOS menus do: "Split Right and Choose…", "Split Down and Choose…", "Split Left and Choose…", "Split Up and Choose…" and "New Space and Choose…". Its key is the item's with ⌥ added: ⌥⇧⌘D and ⌃⌥⌘T work, but macOS takes ⌥⌘D (Turn Dock Hiding On/Off) while that system shortcut is on. New Tab has none: ⌥⌘T is Open Session. From the keyboard, Replace Pane (⇧⌘R) on the new agent, browser or plugin pane gives the chooser, and the palette's Start Agent Here and Open … Here change any pane's kind (Commands that change a pane's kind).
• An agent that is not installed on the window's machine (Agents that are not installed) is not picked: the chooser shows, with that agent dimmed. Until the window's check answers, every agent counts as installed, as in the chooser, so a new window's first pane can type an agent that is not there; the terminal then shows what the command printed.
• Not for panes that ask for their own kind: Replace Pane, the Open … Here and Start Agent Here commands, Resume of an archived session, ovvi agent and ovvi open. The ovvi CLI makes no plain new pane.
• A plugin pick opens through the key window of the pane's session. The first space of a session the app started picks through any window that shows that session; with none, the chooser shows.

Look

A compact list in the middle of the card, on the card's own fill. The terminal stays hidden under it, so no prompt text shows. There is no panel, no title and no key hint. While the chooser shows, the card's header says "New Pane", and a new tab's capsule says "New Tab".

• List. At most 300 pt wide (the card's width less 24 pt), as tall as its rows (at most the card's height less 16 pt). Rows are 28 pt tall and 2 pt apart.

• Row, from the leading edge, 8 pt in: the kind's symbol in a 22 pt column (terminal, sparkles, then each manifest's icon: globe, folder, source.branch, in secondary), the name in 13 pt (a manifest's chooser), then on the right a short description in 12 pt ("Shell", "Coding agent", then each manifest's description: "Web page", "Files and folders", "Changes and history") and the row's number key in 11 pt, both tertiary. The plugins' rows come in the registry's order: Browser, the default plugins, then the user's by id. A plugin whose Show in New Pane switch is off on its page in Settings ▸ Plugins has no row (The Plugins page). The description hides on a card narrower than 300 pt.

• Agent has a 9 pt chevron after its name: chevron.right when closed, chevron.down when open, with its symbol in the accent. Open, it shows its agents under it, 28 pt in, each with its program tile (Program icons) and its command in monospaced text as the description:

  Agent	Command
  Claude Code	claude
  Codex	codex
  Pi	pi
  OpenCode	opencode

  An agent that is not on the machine has a dimmed row. "Not installed" in 11 pt secondary text, dimmed with the row, takes the place of its command and its number key (Agents that are not installed).

• Folder line. 12 pt under the list, one centered line in 12 pt (The folder).

• Selection. The palette's accent pill (Command palette), with the row's text and symbol on the accent. It moves in the same frame, with no fade.

• Increase Contrast gives the descriptions and keys the secondary color.

• Motion. A split's new card slides in with the list already on it. Agent opens and closes over 0.15 s, at once on a card that then needs to scroll. After a pick the list fades out over 0.15 s while the terminal fades in. Reduce Motion makes each change at once.

• Small cards. A card lower than the list scrolls it to the selected row. Only such a card has a scroll view, the list's dearest part to make. A card lower than the list and the folder line has no folder line. A zoomed card and a floating window (Replace Pane on a floated agent pane) show it in their middle, with the same rules.

Keys and pointer

The chooser has the keyboard as soon as it shows: its card is the keyboard card. The app sends the chooser its keys before any terminal, so a fast ⌘T and Return never reaches the old card's shell.

• ↑ and ↓ move the selection. ↑ on the first row goes to the last row, and ↓ on the last row goes to the first row. They skip an agent that is not installed.
• Return picks the selected row. On Agent it opens or closes the agents, and open selects the first installed agent.
• → on Agent opens it. ← and Esc close it again, with Agent selected.
• Esc on a closed list picks Terminal.
• Tab and ⌘L (Open Location) make the folder line a field (The folder). While the field has the keyboard, the keys type into it.
• A number key picks the row with that number. While Agent is open, 1 to 4 pick the agents. The key of an agent that is not installed does nothing.
• Type-select. Typed characters select the first row whose name starts with them, else the first row with a word that starts with them, case-insensitive: file selects File Explorer, br Browser, pi the Pi agent. Nothing opens; Return picks as usual. An agent's row opens Agent. The typed text shows nowhere, and a key typed more than a second after the last one starts a new word. With no match, the selection stays. Digits stay number keys, and an agent that is not installed is never selected.
• A held key moves on, but picks only once.
• Keys after a pick. After Terminal or an agent is picked, the card keeps the keys typed until the new pane's terminal has the keyboard, and then sends them to it as typed: a fast ⌘T, ls and Return (also with a fixed pick) runs ls in the new shell, never in the old card. An agent gets them once it is ready. If the terminal does not get the keyboard (the window went to the back), the keys are dropped with a beep. While a browser or plugin pane opens, each key beeps. Held keys go in as plain keys: a dead key or an input method does not compose, ⌥ types its character whatever Settings ▸ Terminal ▸ Option key says, and ⌘V pastes the clipboard's text.
• The pointer selects a row once it moves, as in the palette. A click picks. A click beside the list gives the card the keyboard.
• Other keys do nothing, also ⌃ and ⌥ chords, so ⌃D cannot end the hidden shell. The app's ⌘ shortcuts (⌘T, ⌘W, ⌘K, ⌘[ and others) and text fields work as usual. When the keyboard moves to another card, the chooser stays on its card and has the keyboard again when the card does.

The folder

The folder line says where the pick starts: "Opens in ~/code/ovvi". It shows in the card's first frame, before herdr has made the pane. At first the folder is the one herdr starts the pane's shell in, which the app knows from its snapshot by herdr's own rule (resolve_new_terminal_cwd in herdr's src/app/creation.rs):

• A split starts in the folder of the pane it splits.
• A new tab starts in the folder of the space's keyboard card, which the app gives herdr.
• A new space starts in the folder the app gives herdr (the home folder by default).

This is herdr's rule with its default new_cwd (follow). Once herdr answers, the line shows the folder herdr gave the pane, which differs only when herdr has another new_cwd or the shell moved to another folder since herdr last reported it. The line can be edited once herdr has made the pane.

• Look. "Opens in" and the folder are tertiary (secondary with Increase Contrast), the folder in medium weight. Only the field is primary. The folder shows short, as File Explorer's path bar shows it: the home folder is ~. A long folder loses its first parts. On a remote machine the line ends with "on ‹machine›".
• Edit. A click on the folder, Tab or ⌘L makes the line a field in File Explorer's capsule with the accent border. The field shows the whole path, selected. Return takes the typed folder. Esc, or a click somewhere else, puts the line back with no change.
• Typed paths. The pane's machine reads the path in its shell. ~ is the home folder there, and a relative path starts at the shown folder. The folder shows with its links resolved (/tmp is /private/tmp).
• Error. If the folder is not on the machine, "No folder ‹path›" shows in 11 pt red on its own line under the field. The line has room for it at all times, so the list does not move. The old folder stays, and the field keeps the typed text.
• Choose Folder. The folder icon at the line's leading end, before "Opens in" and in the field before the path, as in File Explorer's path bar, opens the macOS folder panel at the folder. The icon is only on This Mac: the Mac's panel cannot show the folders of a remote machine.
• The pick. Terminal and an agent type cd -- '‹folder›' into the shell first, as Go to Directory does. A plugin pane is made in the folder. The folder is for this chooser only: the app does not save it.

Terminal

The list fades out and the terminal fades in over 0.15 s, with the keyboard. The shell has run and streamed since the pane was made (the chooser hides it by the view's alpha), so there is no wait. Picked before herdr has made the pane, the card shows the shell as it comes, and the chooser stays out of sight until the terminal has the keyboard, holding the typed keys (Keys after a pick). Then the folder line's cd and the held keys go in.

Agent

A pick types the agent's launch line and Return into the pane's shell, as Go to Directory types its cd (Command palette). The line is the command, the agent's extra arguments from Settings ▸ Agents, then Ovvi's chat flags, so the pane gets a chat view (Settings). Agent lists only the agents whose switch is on in Settings ▸ Agents; with all four off, the list has no Agent row. For Pi and OpenCode, one run on the pane's machine first writes the files the line needs (Launch flags). On a remote machine the shell and the agent run on that machine. An agent in a pane starts another the same way, loader included, with ovvi agent <name> (CLI).

• The loader. The card shows the agent's program tile at 44 × 36 pt in its middle. 12 pt under it is one centered line: a small spinner left of "Starting ‹agent›…" in 13 pt secondary. The terminal stays hidden.
• Ready. The app asks herdr for the pane (pane.get) every 250 ms. The agent is ready when herdr reports it (agent set) with a status other than unknown. herdr reads the status from the screen with its detection manifests, so this works on remote machines too. All four agents report unknown 0.3 to 0.7 s after the command, then idle (or blocked on Claude Code's trust prompt) after 3 to 5 s.
• At ready, the app reads the pane's foreground processes once (pane.process_info), so a pane with a launch marker gets its Chat | TUI switch at once. The loader fades out over 0.15 s and the agent's TUI fades in, with the keyboard. The card opens on the chat after Relaunch with Chat, and when Settings ▸ Agents ▸ Open new agents in is Chat.
• The bare-command fallback. When the shell is the foreground process again in two checks in a row, from 1 s after the line (Program icons), the app types the bare command (claude, codex, pi or opencode) once more, with no extra arguments. An agent build that refuses Ovvi's flags, or a wrong extra argument, then starts with no chat.
• Failure. When the shell is in front again after the bare command too (the command failed or ended), or after 10 s with no ready status, the terminal shows the same way, with what the command printed (for example "command not found: opencode"). No other message.

Agents that are not installed

An agent that the machine does not have still shows, dimmed, and takes no pick.

• The check. Each window checks its machine one time, when the window opens. One command runs on the machine through the window's connection: $SHELL -ilc 'echo; for c in claude codex pi opencode; do command -v $c >/dev/null && echo $c; done; echo ovvi-end'. The first echo puts the agents on their own lines after any text from the startup files. The last line marks a loop that ran. The login shell runs the user's startup files, so the shell's PATH and aliases count. The check stops after 3 s.
• Unknown means installed. Until the check answers, and when it fails, stops or cannot run the loop (fish), every agent is enabled. So no row turns grey and back. A check that failed runs again when the window connects to its remote machine.
• Kept for the window. The answer stays on the window until it closes. The app does not save it and does not check again. To see an agent that you installed after the window opened, open a new window.
• New Pane never waits for the check.
• The row. A click does nothing, and the pointer does not select it. Its hover tip gives the install command, for example "Install Codex: npm install -g @openai/codex".

Browser

Browser, File Explorer, Git and every other plugin row work the same way. A pick turns the pane into a browser or plugin pane with Replace Pane's steps: the labeled pane takes the old pane's place and size, and the old pane closes (Create). Meanwhile the card shows the kind's loader: its symbol (globe, folder or source.branch), and under it a spinner and "Opening Browser…", "Opening File Explorer…" or "Opening Git…". The loader stays until the snapshot that puts the new pane in the old one's place, so the old pane's shell never shows.

• Browser fades in with an empty address field that has the keyboard (Browser).
• File Explorer shows the tree of the git repository that the folder of the folder line is in, else of the folder. Git shows that repository's Git home: its changes, Commit and the history of every branch (File Explorer and Git).
• Another plugin opens on the folder of the folder line: the root of its git repository, else the folder, when its manifest opens folders or git, else with an empty argument.

Commands that change a pane's kind

These commands turn the keyboard card into another kind. They are in the File menu and the card's context menu, between Replace Pane and Close Pane, and in the palette. They have no shortcut.

• A pane's kind: a browser or plugin pane has its kind's label, an agent pane is one where herdr reports an agent, and every other pane is a terminal (also one that runs vim or a server).
• All of them use Replace Pane's steps: the new pane gets the old one's place, size and folder, and the keyboard, and a zoomed or floated pane stays so (Pane card).
• They ask first as Replace Pane does, unless the pane runs only its shell or a browser or plugin pane's placeholder. The dialog is Replace Pane's ("Replace “‹name›”?"), and its red button names the command: "Open Terminal", "Start ‹agent›", "Open Browser", "Open File Explorer" or "Open Git".
• On a pane that shows the chooser, Start Agent Here and the Open … Here commands act as the chooser's picks, with no question.
• A floating window's palette and menu bar offer them too.

VoiceOver and identifiers

• The list is a group named "New Pane". Each row is a button named by its option ("Terminal", "Agent", "Browser", "File Explorer", "Git", "Claude Code", …), with the selected trait on the selected one. Agent's value is "expanded" or "collapsed". The row of an agent that is not installed is dimmed, and its value is "Not installed".
• When the chooser shows, VoiceOver moves to the selected row. The loader reads "Starting ‹agent›" or "Opening ‹kind›".
• Identifiers sit on the leaf elements, after the card's pane.‹id›: pane.‹id›.chooser.terminal, .agent, .browser, .explorer, .git (a plugin row's is its id), .claude, .codex, .pi, .opencode, and pane.‹id›.loader for the loader.
• The folder line: pane.‹id›.chooser.folder is the folder, a button named "Opens in" with the whole path as its value. .folder.field is the field, .folder.error the error and .folder.choose the folder icon.