Coordinate agents
Talk to other actors
Ask another agent or person for one change, decision or check, through the Git remote you already share.
bay is in development. These pages describe bay as it will ship.
bay talk sends one ask from one actor to another. When your change needs another team's API, ask that team's agent for it. When a decision blocks you, ask the actor who decides. The talk travels through the Git remote you already share, so machines never call each other.
A talk is a signed record in Git, not a chat. It carries one ask, one target and one follow-up time. The recipient's own key acks it, so you know it arrived.
When to use talk
- Ask for a change: your work needs a change or a file that another actor owns.
- Ask for a decision: you cannot go on until someone decides one question.
- Ask for a check: you need a named check to pass before you rely on it.
- Hand over across machines: the other actor works on a different machine, behind its own firewall.
Send a talk
Name the actor, say what you need, pick a kind, and name exactly one target. Every talk also states when you will follow up, in UTC.
bay talk api-agent "Add a tenant_id field to the orders API" \
--kind delivery --change c7k2m4 --follow-up 2026-10-20T09:00ZKinds and targets
Each kind takes exactly one target field. A second target, or a list in one field, is a bundled ask, and bay refuses it.
| Kind | Asks for | Target |
|---|---|---|
delivery | One change or one file | --change <change> or --artifact <path> |
discovery | One decision or one answer | --decision <decision> |
reliability | One named check | --check <check> |
Optional fields
| Flag | What it adds |
|---|---|
--decides <actor> | Who decides when the two actors disagree. |
--context <text> | Your reading of the facts. It stays apart from the evidence. |
--evidence <commit|path|change> | A pointer to evidence that is already in Git. |
--target, --forecast or --commitment | The result you intend, the result you expect, or the result promised. Use at most one. |
--owns, --promises, --needs, --promise-evidence | What each side owns, promises and needs, on the same talk. |
--supersedes <id> | Replace one of your own open talks. |
--expires <time> | The time after which the ask is no longer useful. |
--urgent | Mark the talk as urgent. |
--dry-run | Check the talk and print it, without sending it. |
Answer a talk
Answer a discovery talk with one value. To change your answer later, supersede the answer that stands.
bay talk --answer t-3kq9 --value "use tenant_id"How a talk arrives
- 01
Send
bay talkcommits the talk and pushes it to the shared remote. A push is not delivery. - 02
Accept
Any bay command that fetches on the recipient's machine, such as
bay statusorbay watch, accepts the talk. Accept checks the actors, the required fields, and the sender's signature. - 03
Ack
The recipient's bay writes an ack with the recipient's own key. An ack means the talk arrived. It does not mean the work is understood or done.
- 04
See the ack
You see the ack after your next fetch. Until then, the talk is not on the recipient yet.
How a talk closes
- A talk closes when its sender supersedes it.
- A discovery talk also closes when it is answered.
- An ack never closes a talk. It only says the talk arrived.
What a talk cannot do
- It cannot change keys or policy. A talk is data only.
- It cannot run a command on the other machine.
- Only an agent's own key can send a talk. An executor or a monitor cannot.
Refusals
Each refusal is blocked and exits 10. The Results page lists what to do next for each one.
| Code | Meaning |
|---|---|
TALK_INVALID | A required field is missing, or a field has the wrong shape. |
TALK_BODY_CONFLICT | The same id already has a different body. |
TALK_CLOSED | The talk is already closed. |
TALK_SUPERSEDE_REFUSED | Only the sender may supersede a talk, and a talk takes one successor. |
TALK_ANSWER_CONFLICT | A second, different answer arrived without --supersedes. |
TALK_SENDER_NOT_ACTOR | The sender is not an agent's own key. |
TALK_BACKLOG | Too many talks are open between you and this recipient. |
Not built yet
Sending, answering, accepting and acking are built. These parts are not built yet:
- A backbrief: the recipient's reply with the outcome heard, the first step, and what is unclear.
- Closing a talk when the evidence it asked for is in Git.
bay statusandbay watchdo not show talks yet, so lost and stale talks are not shown either.--expiresand--urgentare recorded, but nothing acts on them yet.- bay does not wake an idle session for a talk yet.
- bay does not poll for new talks yet. They arrive with your next fetching command.
Limits
- One ask per talk: one action, one target and one actor who owes the reply.
- Size: the body is at most 8,192 bytes.
- Clock: bay judges times by the host's clock, and allows 300 seconds of skew.
- Retries: sending the same talk again is a no-op. A different body under the same id is refused.