Herdr Workspaces for Pi, Codex, and Antigravity CLI
Herdr is a terminal workspace manager for AI coding agents. Its background server owns real terminal processes, so work inside a pane can continue after the client closes, detaches, or loses its SSH connection. Herdr also identifies agents in panes and rolls states such as working, blocked, done, and idle into a sidebar.
Herdr answers where terminals and agents are, what they are doing, and how to reconnect to them. It does not provide code isolation, permission approval, or Git ownership. Parallel writers still need separate worktrees.
Divide the workspace by responsibility
Herdr's concept model has five useful layers:
- a session is an independent background server namespace; most users only need the default session;
- a workspace represents one repository, task, or investigation;
- a tab separates views such as agents, logs, and servers;
- a pane is a real terminal that can run a shell, agent, test, or service;
- an agent is a process that Herdr recognizes inside a pane.
This structure separates terminal layout from code ownership. Herdr may show three agents in one workspace, but it cannot prevent them from overwriting the same file.
Install Herdr and the three integrations
The official installation guide gives this direct installer for Linux and macOS:
curl -fsSL https://herdr.dev/install.sh | sh
herdr --version
Install the official integrations for CLIs already on the machine, using the targets in the integration reference:
herdr integration install pi
herdr integration install codex
herdr integration install antigravity-cli
herdr integration status
The three integrations report different information, as described in the integration reference:
| Agent | What the integration adds | Source of lifecycle state |
|---|---|---|
Pi | Lifecycle reports and a native session reference | Direct reports from the Pi extension |
Codex CLI | Session identity for restore after a restart | Herdr screen detection |
Antigravity CLI | Conversation ID after the first prompt, used for restore | Herdr screen detection |
The Antigravity CLI hook runs on PreInvocation. A new agy pane must therefore send at least one prompt before Herdr knows its conversation. Herdr restores it with agy --conversation <id>.
Daily operation
Start Herdr from a project directory, then run agents in separate panes:
cd ./repository
herdr
# Run these in separate panes
pi
codex
agy
A new user can work entirely with the mouse: click panes and tabs, drag split borders, and use the right-click menu. The keyboard guide defines the default prefix as ctrl+b. Press it, release it, and then press ? to see the bindings that are active. Its starter actions include:
prefix+vto split right;prefix+minusto split down;prefix+cto create a tab;prefix+qto detach while background work continues.
Run herdr later on the same machine to reconnect. To stop the default background session rather than detach, use the documented herdr server stop command:
herdr server stop
For remote work, the simplest path is normal SSH: connect to the machine and run Herdr there. The remote workflow guide also documents a thin client over SSH, using an SSH-config host such as herdr --remote workbox or an explicit target such as herdr --remote ssh://you@server:2222. SSH authentication and host verification remain the transport boundary; Herdr does not require exposing its local socket to the network.
Know what survives
The session-state reference distinguishes three recovery paths that are easy to confuse:
| Event | What survives | What is not guaranteed |
|---|---|---|
| Client detach and reattach | Pane processes, layout, recent screen contents, and the conversation | Transient client UI state |
| Normal server restart | Workspace, tab, pane, cwd, layout, and focus; eligible native agent sessions can resume | Continued life of arbitrary shells, tests, servers, or other processes |
herdr update --handoff | Attempts to preserve pane PTYs, processes, agent identity, and durable metadata across server replacement | In-flight requests, streams, messages, or transient coordination |
A plain herdr update uses the normal stop-and-restart path. Live handoff only runs when --handoff is explicit. An integration that can resume a conversation does not imply that Herdr can revive every process.
Keep the control boundaries separate
Use Herdr as a terminal control plane:
- assign one workspace to one clear project or investigation;
- assign one writer to one checkout or worktree;
- use project rules in Pi, Codex, or
agyto constrain scope; - let Herdr provide state, layout, detach, and reconnection;
- use Git diffs, tests, and independent review to decide whether work is complete.
If sidebar state looks wrong, run herdr integration status, confirm that the agent started inside a Herdr pane, and verify that the integration was installed for the same user. Then use the documented herdr agent list and herdr agent explain commands to inspect how Herdr classified the pane.