Introduction

Ovvi is a native macOS client for herdr, a terminal multiplexer for AI coding agents: a program that keeps terminals alive in spaces, tabs and panes. herdr stays the backend. It owns every space, tab, pane, terminal and agent. The app draws them, drives them, and keeps as little state of its own as it can.

These pages describe the app as it is built. It needs macOS 26 and herdr 0.9.3 (protocol 22) or newer on each machine; the Mac needs herdr only for its own sessions. Ideas for later are in Future work.

The problem

People run many coding agents (Claude Code, Codex, pi) at once, often on several machines. herdr keeps those agents alive in panes on each machine and knows when each one is working, blocked or done (the app shows these as working, needs you and finished). But herdr's interface is a terminal UI: one machine at a time, keyboard first.

What the app does

A window per machine shows its herdr sessions as sidebar pages and each tab as a page of live terminal cards laid out the way herdr splits them. Everything it does is in Features.

Principles

1. The multiplexer is the source of truth. If herdr can hold a piece of state, it holds it. A fresh app on a new Mac rebuilds everything from it. Everything the app keeps for itself is listed in Data.
2. Use what exists. herdr's API and CLI, OpenSSH, Apple's frameworks. On a remote machine the app only runs commands over SSH. No daemon or server of our own; the one exception is the relay, a script sent with each SSH connection, never installed, gone with it (Machines).
3. Never send the user to herdr. Everything a user does with sessions, spaces, tabs, panes and machines is done in the app. No text in the UI tells the user to run a herdr command; where there is nothing yet, the app shows the button that makes it. The one exception: when herdr is not installed, the page shows the install command, because the app cannot install herdr.
4. The simplest thing that works. Each shortcut we take on purpose is marked "Simpler choice" and says when to revisit it.

Read the design