A Mac app for herdr your agents' terminals, with a native front end

What herdr is

herdr describes itself as a "terminal workspace manager for AI coding agents". It is a single binary: a background server owns real terminals, and the full-screen terminal app is a client that attaches to it. It works like tmux, with workspaces, tabs, panes and a ctrl+b prefix, plus one thing tmux does not have: it knows which coding agent runs in each pane and what state it is in. It runs agents unmodified; it does not wrap them.

herdr is free and open source under the Apache-2.0 license, and is built by Herdr, Inc.

Four ideas cover most of it:

• A persistent session. A herdr server owns the terminals. Close the window and the agents keep running; run herdr again to attach.
• Workspaces, tabs and panes. The same layout ideas as tmux, with IDs like w1, w1:t1 and w1:p1.
• Agent detection. herdr recognizes the coding agent running in a pane and reports one of five states: idle, working, blocked (an approval or question is on screen), done or unknown.
• A command line and socket API. Most herdr subcommands talk to the running server and return JSON, so scripts and other apps can read panes and send input.

herdr's site says it detects 22 agent CLIs out of the box, including Claude Code, Codex, Copilot CLI, Cursor Agent, OpenCode, Pi, Omp, Droid, Grok CLI, Amp and Gemini CLI. Most are recognized by reading the bottom of the pane's screen; a few report their own state through an integration.

Install herdr

Use the install script from herdr's site, or Homebrew:

curl -fsSL https://herdr.dev/install.sh | sh
# or
brew install herdr

herdr --version

herdr has builds for macOS on Apple Silicon and Intel, Linux on x86_64 and arm64, and Windows in beta. If you used the install script, herdr update installs new versions.

Use herdr from the terminal

Open the workspace and start agents

Run herdr to launch the session, or attach to it if it is already running. Split panes, open tabs, and start claude, codex or another CLI in a pane as you would in any terminal. herdr notices the agent and labels the pane.

Named sessions keep projects apart: herdr --session api opens or creates one, herdr session list shows them, and herdr session attach api brings one back.

Check on agents without switching panes

From any terminal, the agent commands work on the running session:

herdr agent list                         # every agent, its pane and its state
herdr agent read reviewer --lines 80     # recent output from one agent
herdr agent prompt reviewer "Run the tests and report failures." --wait
herdr agent wait reviewer --until blocked --timeout 600000
herdr agent attach reviewer              # open its terminal here

Targets are an agent's name or the pane ID it runs in. herdr agent rename gives an agent a name, and herdr agent start reviewer --kind codex --pane w1:p2 starts a supported agent in an empty shell pane with that name. agent prompt refuses to type into an agent that is blocked on an approval, so a script cannot answer a permission prompt by accident.

Worktrees and other machines

herdr worktree create makes a git worktree and opens it as its own workspace, so two agents in one repo can work on separate branches. herdr machine add saves an SSH machine and prepares its herdr server; after that, herdr --machine <name> agent list runs the same commands there, and herdr --remote <ssh-target> attaches to a remote session.

What the terminal leaves to you

herdr knows each agent's state, but you still have to look. With the workspace in one window and your editor or browser in front, a blocked agent waits until you happen to check. Answering means attaching to the right pane, reading back to find the question, and typing the answer in that agent's own format. herdr has no official phone client.

That is the part a front end can do: watch the server for you, bring each question to one place, and send your answer into the right pane.

Mac apps that work with herdr

None of these are made by the herdr project. They all talk to the same herdr server, so your agents keep running whichever one you open.

herdrm and Herdr UI are the closer match if you want herdr's own workspaces, tabs and panes in a Mac window. Cadence is the closer match if you want to stop watching panes at all and answer agents from wherever you are. On the phone, community apps such as Whip connect to herdr over SSH.

Cadence: a Mac front end for herdr

Cadence is a free macOS app that talks to herdr over its socket API. It uses herdr for every agent that is not Claude Code, and for Claude Code too when you pick the Terminal mode. Because it reads the same server, agents you start in herdr yourself show up next to the ones Cadence starts.

Set it up

1. Download Cadence (macOS 13 or later, Apple Silicon). There is no account.
2. Open ⋯ → New agent… on the toolbar. If herdr is missing, the view shows the install command; run it and click I installed it. If herdr is installed but its server is not running, click Start herdr.
3. Pick a CLI (Codex, OpenCode, Pi, Omp, Amp, Grok, Cursor, Copilot, Gemini, or Claude Code in Terminal mode), a Folder and an optional First message, and start it.

Each agent opens in a terminal window attached to its herdr pane. Pick Terminal, iTerm or Ghostty in Settings → Agents → Open Cadence's agents in. Closing the window or quitting Cadence leaves the agent running in herdr.

A toolbar instead of a pane list

The toolbar on the edge of your screen shows one dot per agent: blue working, amber needs you, green done. It stays above other windows on every Space, so you see a blocked agent without opening herdr. Every agent gets a short title written from what it is doing, like "settings page dark mode", instead of a pane ID.

One Inbox for every question

When a herdr agent prints numbered options or a yes/no question, it lands in the Inbox as a card. Press 1 to 9 to pick, Space to type, or V to speak, and Cadence types the answer into that pane. Esc takes an answer back within two seconds. Finished work arrives as a card with a short recap.

Talk and the Director

Double-tap ⌥ and say "tell the Codex agent to add pagination" or "start a Codex agent in the api folder". Talk sends it to the agent already on that work or starts a new one in herdr. The Director can read herdr agents by name, message them and close them, so "is anything stuck?" covers all of them.

Your phone

The Cadence iPhone app, in a private TestFlight beta, shows the same agents and answers them from the app, a widget or Siri. It pairs with your Mac by QR code, and traffic between them is end-to-end encrypted. Your herdr agents reach the phone through your Mac.

Agents on your servers

Since Cadence 0.5.7, agents running in herdr on a Linux server show up on the toolbar, in the Inbox and on your phone under the server's name, and you answer them the same way.

1. Open Settings → Agents → Other machines and copy the command it shows.
2. Run it on the server. It installs herdr and, if your Mac has an SSH key, lets your Mac sign in with it. It does nothing else.
3. Back in Cadence, enter the server's SSH address, like you@203.0.113.7, and click Add.

Cadence connects through herdr's own saved SSH machines, over your Mac's OpenSSH and your own keys. Nothing on the server talks to Cadence or your phone. Start the agents on the server inside herdr (run herdr, then claude or codex in a pane); starting and ending agents on a server still happens on the server. The guide to coding agents on a server covers the server side step by step.

Common questions