openrig-herdr · git:20261025.bd617c4 · 2026-10-25 · sha256 cb39b51f954ca89e
openrig-herdr git:20261025.bd617c4A
Immutable. This exact content never changes and is served at /api/v1/blob/cb39b51f954ca89e.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_z322hk3kgtonfjhq/cb39b51f954ca89e8d7ec0f8b3f326476d5c4dd3bc17dbd47e6379aa630e7b22.json
Then /plugin install openrig-herdr@markdownregistry-z322hk3kgtonfjhq in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: openrig-herdr
description: >
Use when opening OpenRig fleet terminals as a herdr wall — turning a rig, pod, mission, slice, or
saved view into live interactive agent tiles via `rig terminal`, watching another rig read-only,
or driving herdr on an agent's request ("open all my rigs + a mission as views"). Covers the
`rig terminal open|views|status` verbs, the honest-partial/degrade reading of the result, the
read-only-by-construction rail for cross-rig views, scroll/copy out of the box, and the
same-size-only duplicate-pane limit. herdr is the default, proof-gated provider.
metadata:
openrig:
stage: candidate
sibling_skills:
- openrig-cmux
- openrig-user
---
# openrig-herdr
OpenRig decides **which** agents make up a view (a rig, a pod, a mission, a slice, or a saved
group); **herdr** renders the pixels. A view opens as live, interactive terminal tiles — each tile
is a nested `tmux attach` to a daemon-owned agent session, so you get the real session, not a
snapshot. OpenRig owns the semantics; herdr owns the surface. You drive it entirely through the
`rig terminal` CLI, which rides the installed herdr binary at arm's length — never link, embed, or
plugin it.
## The whole surface — three verbs
```bash
rig terminal open <view> [--provider herdr|cmux|rex] [--json] # herdr is the default provider
rig terminal views [--json] # list openable views (saved + derived)
rig terminal status [--provider] [--json] # provider liveness / health
```
Inside Rex, `rig terminal open <view> --window` opens the view as a new Rex session instead, on the same Rex
server as your terminal, and asks the Rex app to show it. `--provider rex` opens it there from anywhere.
`<view>` resolves, in order, to one of:
- a **rig name** — every live agent in that rig, auto-laid-out;
- **`pod:<rig>/<podNamespace>`** — every live agent in one pod of a rig (the rig's inventory filtered by pod);
- **`mission:<id>`** — the agents working that mission (derived live from topology);
- **`slice:<id>`** — the agents working that slice (derived live);
- a **saved-view name** — a user-defined group (see Saved views).
## Compose a view from a sentence
An agent asked "open all my rigs plus a mission as views" runs one `open` per target:
```bash
rig terminal open acme-web # a whole rig, live agents as tiles
rig terminal open mission:site-relaunch # exactly the agents working the mission
rig terminal open slice:search-filters # the agents working one slice
```
No hand-listing of seats: the mission/slice membership is derived from live topology at open time.
## Read the result honestly — partial and degrade
The result is a partition — every seat lands in exactly one bucket, each **named**:
- **opened** — the live agents now showing as tiles.
- **absent** — seats in the view that aren't currently live: **named and skipped, never silently
dropped.** A view that opens *some* of its seats is a success (the partial is disclosed) and exits
**0**. Only a view where **no** pane opens exits **non-zero**.
- **degraded** — an agent that structurally cannot tile, named **with the reason**. The v1 case:
an agent on a host registered over HTTP has no ssh path, so its tile can't be composed — it reads
as **"host `<id>` is http-registered; tiles need ssh"** and is skipped, never dropped. (ssh-reachable
hosts tile via an ssh-wrapped attach; full http-host tiling is deferred to the cross-host transport
seam.)
Read `--json` to branch on the partition programmatically; the exit code alone tells you opened-something
(0) vs opened-nothing (non-zero).
## Read-only — who's interactive, who's watch-only
Read-only is composed into the pane at open time — a read-only tile is a `tmux attach -r`, the client
reports `readonly=1`, and it **physically cannot send input**. The current policy, by view kind:
- **A rig view or a `pod:` view is interactive** — you asked for that rig (or pod) directly, so you
can drive its agents.
- **`mission:` and `slice:` views are read-only by construction** — these derived views cut across
rigs; you watch and scroll, you don't keystroke into them.
- **A saved view is per-member** — each member carries its own `readOnly` (omit = interactive;
`true` = `attach -r`).
So you don't have to remember to be careful: the view kind (and, for a saved view, the per-member
flag) sets it at open time.
## Safety rails (hard — the fleet-safety rail)
- A tile is a **view** (a nested `tmux attach`) of a daemon-owned session. **Never** move, join, kill,
or re-parent a daemon-owned pane. Closing a tile detaches one tmux client — the daemon's session is
untouched and its addressing (send/capture/nudge) is unaffected.
- Host-local read-only viewing mutates nothing. Anything that would change a **live** daemon session's
shared state (e.g. flipping a tmux option on a running seat) is a config/design change — prove it in
an isolated environment, never live-flip in production.
## Scroll + copy work out of the box
On a freshly-launched agent tile the mouse wheel scrolls the pane's history and a drag-select copies
to your **system** clipboard — with no tmux commands typed. This rides the daemon's terminal defaults
(a per-session scroll option set at launch, plus the daemon tmux server's clipboard defaults). Honest
timing: agents that were already running before this shipped pick up wheel-scroll at their **next
natural relaunch** (the scroll default is per-session and running seats are never retro-flipped);
system-clipboard copy works immediately (it's server-wide).
## Limits — state them, don't paper over them
- **Tile chrome v1 = a plain label** (agent + slice). Rich per-tile status is roadmap.
- **Duplicate / multi-view membership** (the same agent live in two views at once) works — put the
duplicates in **same-size panes**. Different-sized duplicate panes have an inherent tmux
multi-client resize mismatch (tmux clamps to the smallest client); it is **documented, not fixed** —
don't expect a setting to remove it.
- **Inner tmux status bar** is hidden by default (herdr provides the chrome); one config key
(`terminal.status_bar`) flips it back on for raw-tmux / no-provider surfaces, and the flip applies
to **future launches only**.
- **Coming back to a view:** each `rig terminal open <view> --provider herdr` adds a new workspace,
numbered when the name is taken (`<view> (2)`). To come back, focus the view's open space in Herdr.
From inside Herdr, `rig terminal open <view> --window` focuses a matching space with live tiles
instead of adding one.
- **After a Herdr server restart or update** (without `--handoff`), Herdr restores the layout and
labels. A tile reattaches when Herdr took its restart command at open (Herdr 0.9.2 or later). The
open result names a tile whose command Herdr didn't take; a tile over SSH, or for a runtime Herdr
doesn't recognise, has none. Those come back as empty shells while the seats keep running: reopen
the view, then close the old space.
- **Herdr's status for a tile is Herdr's own reading** of its screen. It can show a seat as idle or
unknown while OpenRig shows it waiting (`needs-input`). Two cases are known: a narrow tile that
wraps Claude's footer, and a tile that shows the inner tmux status line. That line shows when
`terminal.status_bar` is on, or for a seat session OpenRig adopted rather than created, which keeps
its own tmux `status`. To find waiting seats, use OpenRig's own view (`rig ps --nodes` or the TUI)
or the Feed.
## Saved views — the library (`terminal-views.yaml`)
In v1 you **create** a saved view by **hand-authoring** `terminal-views.yaml` — there is no save/write
verb (`open` / `views` / `status` are the whole surface; a `rig terminal save <id>` verb is a named
stretch/follow-up). You **reopen** it like any other view: `rig terminal open <id>`.
The file lives at the OpenRig home root (resolved via `getDefaultOpenRigPath()`), is written
atomically (tmp + rename), and is byte-stable. **Only hand-authored saved views live here — derived
views (a rig, `pod:<rig>/<pod>`, `mission:<id>`, `slice:<id>`) are computed live and never written to
this file.**
Schema — use these field names **exactly**, in this order; **omit** optional fields when absent
(never write `null`):
```yaml
version: 1
views:
- id: my-view-id # required — the id `rig terminal open <id>` takes
name: Human Name # required
members:
- seat: pod-member@rig # required — the canonical session name
label: agent . slice # optional — pane label
host: some-host-id # optional — STRUCTURED host id (NEVER a `member@rig@host` string);
# omit for local. ssh-registered hosts tile;
# http-registered hosts honest-degrade (named + skipped, with reason)
tmuxSession: sessname # optional — defaults to `seat`
readOnly: true # optional — omit = interactive; true = `tmux attach -r`
```
An agent composing a saved view on request **writes this YAML** and then opens the id:
`rig terminal open my-view-id` (add `--provider cmux` for cmux). The library is provider-agnostic —
the same saved view opens in herdr or cmux.
## AGPL / clean-room
Driving herdr through the `rig terminal` CLI (which talks to the installed herdr binary over its
CLI/socket) is arm's-length and fine. Do **not** link herdr's source, embed it in-process, or ship a
herdr plugin — a plugin needs legal review. This skill and its docs are clean-room: patterns only,
never herdr source text.