openrig-herdr — Claude Code skill: what it does, how to install
openrig-herdr opens an OpenRig fleet as live terminal tiles via herdr: a rig, pod, mission, slice, or saved view turns into interactive panes with nested tmux attach to daemon-owned agent sessions.
Apache-2.0 ★ 8,928 updated 2026-11-12
npx skills add mvschwarz/openrig --skill openrig-herdr -a claude-codeWhat openrig-herdr does
The skill teaches the agent to use rig terminal open, rig terminal views, and rig terminal status — commands that turn a group of agents into a wall of terminal tiles. Each tile is a nested tmux attach to a daemon-owned agent session; you see the live session, not a snapshot. The skill explains that a view (<view>) can be a rig name, pod:<rig>/<podNamespace>, mission:<id>, slice:<id>, or a saved group, and how to interpret the result: opened (agents now showing as tiles), absent (seats in the view that aren't live, named and skipped), degraded (agents that structurally can't tile, with the reason — for example, an HTTP-registered host with no ssh path).
mission: and slice: views open as read-only by construction (tmux attach -r), because they cut across rigs; a rig or pod: is interactive. Duplicate tiles (the same agent in two open views) work if the panes are the same size — tmux clamps multiple clients to the smallest, and this is a documented limit. The mouse wheel scrolls pane history, a drag-select copies to your system clipboard without commands — these are the daemon's defaults.
Partial opens are disclosed: if some seats open and some don't, the command exits 0 and names the absent and degraded seats. Only an open where no pane shows exits non-zero.
What it helps with
- open all agents in a rig or pod as live terminal tiles
- watch mission or slice agents in read-only mode without interfering
- interpret open results as a partition: opened, absent, degraded with names and reasons
- open a view on agent request ("open all my rigs plus a mission as views")
- check available views via
rig terminal views
Example prompts for the agent
- open rig
acme-webas a terminal wall - show agents working mission
site-relaunchin herdr - list available OpenRig views
How to install openrig-herdr
1Skills CLI (Vercel)
npx skills add mvschwarz/openrig --skill openrig-herdr -a claude-code2Manually: put the files in place
~/.claude/skills/openrig-herdr/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/openrig-herdr/
1Skills CLI (Vercel)
npx skills add mvschwarz/openrig --skill openrig-herdr -a codex2Manually: put the files in place
.agents/skills/openrig-herdr/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mvschwarz/openrig --skill openrig-herdr -a cursor2Manually: put the files in place
.cursor/skills/openrig-herdr/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mvschwarz/openrig skills/_canonical/core/openrig-herdr2Manually: put the files in place
.github/skills/openrig-herdr/SKILL.md1Skills CLI (Vercel)
npx skills add mvschwarz/openrig --skill openrig-herdr -a gemini-cli2Platform CLI
gemini skills install https://github.com/mvschwarz/openrig --path skills/_canonical/core/openrig-herdrManually: put the files in place
.devin/skills/openrig-herdr/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mvschwarz/openrig --skill openrig-herdr -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about openrig-herdr
How to install openrig-herdr in Claude Code?
Run npx skills add mvschwarz/openrig --skill openrig-herdr -a claude-code, then read ~/.claude/skills/openrig-herdr/SKILL.md.
What does openrig-herdr do?
Teaches the agent to open an OpenRig fleet via rig terminal open: a rig, pod, mission, slice, or saved group becomes live terminal tiles (nested tmux attach to agent sessions). The agent reads the result as a partition: opened, absent, degraded — and understands that missions and slices open as read-only, rigs as interactive.
How is mission: different from a rig?
A mission:<id> view is composed from agents working a specific mission, derived from live topology — membership is dynamic. A rig is a fixed inventory. A mission opens as read-only by construction, a rig is interactive.
Source text
SKILL.md · Apache-2.0
---
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 open <view> --provider herdr-app # in the herdr-app window this runs in; plain open inside herdr-app does the same when the window answers (--window always asks for a new desktop window; the open installs OpenRig's mods there)
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.
© mvschwarz · Apache-2.0 · mvschwarz/openrig