# 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.

[//]: # (table:start)
| 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 |

[//]: # (table:end)

## 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](/docs/coordination): queue rows, handoffs and the views that show who owes what.
- [The terminal UI](/docs/tui): the same seats and messages seen from the operator's side.
- [Hosts](/docs/hosts-and-humans): sending, capturing and reading transcripts on another registered machine with `--host`.