Messaging

Sessions let you read what agents did. Messaging lets you steer one that is running. agents message sends a note to a live agent; it is picked up at the agent's next tool call and folded into its context — no queue, no broker, no daemon.

Send a message

Address a running agent by session id, teams name, or short id, and pass the text. --from labels the sender.

agents message feed-plan "Prioritize gap #3 first; quote the file:line." --from "you@laptop"

Delivery is routed by the target's state — you do not pick the path:

running, between tool calls → written to its mailbox, injected as context on the next tool call.
parked on a question (tmux / iTerm / pty rail) → typed straight into the terminal.
parked headless → re-entered via agents run --resume with your text as the next turn.
a cloud task → the provider's own message API (see Cloud dispatch).

The mailbox

The primary channel is a file spool — three directories per agent, under ~/.agents/.history/mailbox/<id>/. A message is a JSON file that moves through them; the agent drains its own box, nobody pushes to it.

Claim-first (rename into processing/) makes delivery crash-safe and at-least-once. The box id is the agent's session UUID (or a teams id / loop id), so a message can never reach the wrong agent.

The drain is a PreToolUse hook that reads AGENTS_MAILBOX_DIR (set at spawn), so an agent only ever reads its own mail. It is most reliable on Claude; if a steer seems ignored, check the box: ls ~/.agents/.history/mailbox/<id>/inbox.

Inspect the traffic

agents mailboxes is the fleet-comms view over the whole spool — recent messages, a live tail, threads, and an adjacency graph. Its flags are the filter-by-agent controls.

agents mailboxes --watch                        # live-tail every message
agents mailboxes --between you@laptop feed-plan  # a thread, either direction
agents mailboxes --from codex --since 2h         # by sender + window
agents mailboxes --graph                         # who-talks-to-whom, busiest first

Steering a teammate

Teammates in a team do not talk to each other — they coordinate through git and tests. The messaging primitive is for the operator to steer one teammate. A running teammate is steered via its mailbox; a stopped one is resumed into its own session.

agents teams message pricing-page qa "Skip the flaky screenshot test for now"

Supervising blocked agents

When many agents run at once, the bottleneck is decisions they are blocked on. agents feed aggregates every open block across the fleet, grouped by outcome, and each block carries the identity agents message needs to reply. Feed to see who is stuck, message to unblock them.

agents feed                          # open blocks, grouped by outcome
agents message <id> "Go with option B" --from you@laptop

Across machines

A mailbox is local to the host the agent runs on. To steer an agent on another machine, route the write there with --host — the message is written on the box that owns the agent.

agents message <id> "..." --host yosemite-s1 --from you@laptop

Learn: How agents communicate — the memory + messaging story, with diagrams.
Sessions — read what agents did; messaging steers one that's running.
Teams — parallel agents; steer a single teammate by name.
Remote runs — reach an agent running on another machine.