How to use the OpenRig Herdr Terminal Wall agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for a task. When the agent sees a request that matches the skill's description, it reads those instructions and follows them.

openrig-herdr covers one job: turning a set of OpenRig agents into a wall of terminal tiles in herdr. OpenRig decides which agents belong in the view. herdr draws the terminals. Each tile is a nested tmux attach to a live agent session owned by the OpenRig daemon, so you see the real session rather than a snapshot.

• Opens a rig, pod, mission, slice, or saved view as tiles
• Reads the result honestly, naming any seats that were absent or could not be tiled
• Keeps cross-rig views read-only so nothing is typed into them by accident

Install the openrig-herdr skill

Download the skill ZIP from this page. Then choose one of two install routes.

For a personal install that works in every project, unzip the file into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. Either way, the openrig-herdr folder containing SKILL.md should end up inside the skills folder.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Install the requirements

The skill only drives the rig CLI. It cannot work without OpenRig and herdr. The source lists these requirements: the OpenRig rig CLI, the herdr binary installed as the default provider, and tmux, because agent sessions are nested tmux attaches. Remote hosts also need ssh access. Hosts registered over HTTP cannot be tiled.

• OpenRig rig CLI
• herdr binary (default provider)
• tmux
• ssh access for remote hosts

Trigger the skill with a natural request

You do not need to type a command name. Ask the agent in plain language, and the skill is picked up when the request matches its description. Good requests name the thing you want to see: a rig, a mission, a slice, or a saved view, and say whether you want to watch or drive it.

The agent turns your request into one rig terminal open call per target. You can ask for several views in one message.

• "Open all my rigs plus the site-relaunch mission as views."
• "Show me the agents on the search-filters slice as a read-only wall."
• "Open the acme-web rig in herdr so I can drive its agents."

Commands the agent uses

The skill uses three verbs. You rarely type these yourself, but they show what the agent is doing and are useful for checking its work. The open verb accepts a view and a provider, which defaults to herdr.

• rig terminal open <view> to open tiles; add --json for the machine-readable result
• rig terminal views to list views you can open, both saved and derived
• rig terminal status to check provider liveness and health

Understand which tiles you can type into

A rig view and a pod view are interactive, because you asked for that rig or pod directly. Mission and slice views are read-only by construction, since they cut across rigs. A read-only tile physically cannot send input. Saved views set read-only per member.

• Rig and pod views: interactive
• Mission and slice views: read-only
• Saved views: each member sets readOnly (omit for interactive, true for read-only)

Read partial results and failures

Every seat in a view lands in one named bucket. Opened seats show as tiles. Absent seats are not live, and they are named and skipped. A degraded seat cannot be tiled, and the result gives the reason, such as a host registered over HTTP that needs ssh. A view that opens some seats exits 0. Only a view where no pane opens exits non-zero. Use --json to branch on the buckets.

Safety notes and known limits

The skill runs scripts and does not use the network. A tile is a view of a daemon-owned session. Closing a tile detaches one tmux client and leaves the agent running. The skill is told never to move, join, kill, or re-parent a daemon-owned pane.

Known limits: tile labels show only the agent and slice. Duplicate agents in two views work best in same-size panes. Herdr's status for a tile is its own reading of the screen and can differ from OpenRig's. After a Herdr restart, some tiles come back as empty shells, so reopen the view and close the old space.

• Runs scripts: yes. Uses network: no.
• Closing a tile does not stop the agent.
• Herdr status can show idle or unknown while OpenRig shows needs-input. Check rig ps --nodes or the TUI for waiting seats.
• Saved views are hand-written in terminal-views.yaml in v1; there is no save verb.

Tips for a better terminal wall

Keep duplicate-agent panes the same size to avoid tmux resize mismatch. Expect that limit; no setting removes it. Reopening a view adds a new workspace, numbered when the name is taken, so focus the existing one or close old spaces. Scroll and copy work on fresh agent tiles, and agents already running pick up wheel scroll at their next relaunch.

• Use same-size panes for duplicate agents
• Reopening adds a workspace such as "<view> (2)"
• Use --window from inside Herdr to focus an existing space