Messaging: how seats talk

Documented against OpenRig 0.7.7. 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 the recent output OpenRig has captured from a seat's terminal. 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. --urgent marks a message urgent, so it types at a seat whose typing guard holds other messages; the recipient sees who marked it.

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

Ask an online agent with rig send. Demonstration with example seats (slack-original@demo, builder@demo), not live output.

Capture. A still frame of one seat's screen, or every seat in a pod or rig. By default it shows 20 lines of history plus the whole visible pane; --lines N shows exactly the last N lines. --readable reads a seat whose pane is smaller than 120x40: it resizes the window, captures, then gives the window back, and anyone watching sees the resize briefly.

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

Transcript. What has been said in a seat, from the terminal output OpenRig records, with --tail and --grep. The record is a trailing window of the screen, not the whole session: by default the last 1000 lines, captured every 2 seconds (transcripts.lines and transcripts.poll_interval_seconds change both). It is not a guarantee that nothing was missed.

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, pod, mission, slice or task up as tiles in a new desktop terminal (Herdr when it's available, otherwise plain tmux), or with --provider in a Herdr, cmux or Rex that is already running.

Ask an earlier session with rig ask. Demonstration with example seats (slack@demo), not live output.

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`	Delete every message in a rig's chat room	chatroom.clear.txt
`rig chatroom history`	Print a rig's chat messages and topic markers, with filters	chatroom.history.txt
`rig chatroom send`	Post a message to a rig's chat room; the sender is this seat	chatroom.send.txt
`rig chatroom topic`	Start a new topic in a rig's chat room	chatroom.topic.txt
`rig chatroom wait`	Wait for the next matching message in a rig's chat room; exits 1 when --timeout passes	chatroom.wait.txt
`rig chatroom watch`	Print a rig's chat messages as they arrive; --tmux runs it in its own tmux session	chatroom.watch.txt
`rig send`	Send a message to an agent's terminal	send.txt
`rig terminal`	Open the OpenRig view and agent conversations in terminal tiles	terminal.txt
`rig terminal open`	Open a desktop terminal showing the view's live agents as interactive tiles	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. rendered-unconfirmed means the text and Enter landed but the capture could not re-confirm it, which is not a failure; text still unsubmitted at the prompt after one Enter retry ends as staged-not-consumed with exit code 1.
A seat's typing guard (rig seat set-typing-guard --mode, off by default) decides which automatic input types into it. hold holds all of it; draft-aware holds a message only when the input box has a draft in it or can't be read; openrig-urgent and urgent-only let through messages marked urgent, but never over a draft; sends-only types deliberate sends and holds OpenRig's own notices. A held send reports retained. rig seat held-messages reads held messages, and reading never delivers them.
rig seat set-terminal-policy is a separate choice: who may intervene in a seat's terminal, such as compacting it or changing its model. Its presets are no-peer-interventions, help-within-instructions (named helpers, under a delegating instruction) and full-control.
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