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