Messaging: how seats talk

Documented against OpenRig 0.5.14. Help text uses "node" where these pages say seat, for a seat's position in the running rig.

What it is for

Seats talk through their terminals. rig send types a message into another seat's prompt, wrapped in a From and To envelope so the receiver can answer. rig capture reads what is on a seat's screen right now. rig transcript reads what a seat has said, across every session that has occupied it. There is no separate channel between agents and no SDK to learn. If it runs in a terminal, it can be on the team. A message informs. Work that another seat must act on belongs in the queue (see Coordination), because a message leaves no durable obligation behind.

The three verbs you will use first

Send. One seat, several seats, a pod, or a rig. --verify checks that the text appeared in the pane; it does not mean the agent read it. A busy target still receives the text with an advisory. A target sitting at an interactive prompt or permission block is refused, so a normal send can never answer another agent's prompt.

rig send dev-impl@my-rig "the file you want is src/auth.ts" --verify
rig send --pod dev "new task spec at docs/planning/next-task.md"
rig send dev-impl@my-rig "safe proof prompt" --wait-for-idle 30 --verify

Capture. A still frame of one seat's screen, or every seat in a pod or rig. Default 20 lines.

rig capture dev-impl@my-rig
rig capture dev-impl@my-rig --lines 50
rig capture --pod dev --rig my-rig

Transcript. What has been said in a seat, from the terminal output OpenRig records, with --tail and --grep. It is a record of what was said, not a guarantee that nothing was missed, and it is capped by a configurable line count.

rig transcript dev-impl@my-rig --tail 100
rig transcript dev-impl@my-rig --grep "decision|architecture"

The rest of the family

rig broadcast sends one message to every seat in a rig or pod at once. rig ask <rig> "<question>" searches transcript history; without --wake it returns evidence excerpts, not an answer, and --wake deliberately resumes a session to ask it. rig chatroom is durable rig-scoped messaging stored in the database, with history, topics and a wait that blocks until someone speaks, so you do not poll captures in a loop. rig walk delivers a paced sequence of context pieces into a seat one at a time, which is how a seat is onboarded without one dump. rig terminal open brings every live seat in a rig, mission or slice up as tiles in Herdr or cmux.

Command	What it does (from help)	Help source
`rig ask`	Search rig transcript history with a natural language question	ask.txt
`rig broadcast`	Send a message to multiple agent sessions	broadcast.txt
`rig capture`	Capture terminal output from agent sessions	capture.txt
`rig chatroom`	Chat room for rig communication	chatroom.txt
`rig chatroom clear`		chatroom.clear.txt
`rig chatroom history`		chatroom.history.txt
`rig chatroom send`		chatroom.send.txt
`rig chatroom topic`		chatroom.topic.txt
`rig chatroom wait`		chatroom.wait.txt
`rig chatroom watch`		chatroom.watch.txt
`rig send`	Send a message to an agent's terminal	send.txt
`rig terminal`	Open OpenRig views (agent terminals) as tiles in a terminal provider (herdr / cmux)	terminal.txt
`rig terminal open`	Open every live agent in the view as an interactive terminal tile	terminal.open.txt
`rig terminal status`	Show terminal provider availability + liveness (doctor)	terminal.status.txt
`rig terminal views`	List saved views + the rigs openable as derived views	terminal.views.txt
`rig transcript`	Read agent transcript output	transcript.txt
`rig walk`	Walk a seat through a paced sequence of context pieces	walk.txt

What it does not do

A send is not a claim, an approval or a handoff. It creates no row, no owner and no audit entry. Use the queue for anything that must survive the receiver's turn.
--verify proves pane delivery only. A seat mid-task may show nothing on capture and still have the text queued; confirm consequential delivery by its effect.
Normal send refuses to answer an interactive prompt on the receiver's behalf. --raw keeps that guard; the separate dangerous override for driving a prompt is documented in the CLI reference and needs a stated reason.
Capture is a glance, not a feed. Polling captures in a loop burns tokens on a shared provider; use chatroom wait, the queue, or a watchdog to be told instead.

Where it goes next

Coordination: queue rows, handoffs and the views that show who owes what.
The terminal UI: the same seats and messages seen from the operator's side.
Hosts: sending, capturing and reading transcripts on another registered machine with --host.

Read as Markdown