Agent Messaging

  • Desktop app
  • All plans
View as MarkdownFeature page

What it does

The saved agents of a project are permanent members that can write to each other, whichever CLI each one runs. A message is stored in the project before anyone tries to deliver it, so an offline recipient, a crashed CLI or an app restart never loses one. Delivery waits for a good moment: it is held while the recipient is thinking or waiting on your answer. By default no console is started just to deliver mail; a setting, off by default, lets a message bring an offline recipient back in the background. What lands in the terminal is a short notice (sender, subject, preview); reading the body through the inbox tool is what marks it read. Each message shows a trail of separate states: Queued, Delivered, Read, Accepted, Declined, Answered.

An agent started while mail waits for it, by you or by the app, is told in its startup brief to read its inbox before it greets you or asks what to work on.

The human side is Broadcast: one message typed once, written into the console of every agent whose session is currently open, with a per-recipient report (delivered, queued, failed).

Where to find it

  • Agents panel > Organization button (under Add Team), with a badge counting unread messages. The Agent organization modal lists members on the left (status: Available, Working, Needs you, Blocked, Rate limited, Offline) and the selected member's correspondence on the right.
  • Conversations between agents also show as conversation boxes in the agents sidebar, without opening anything.
  • Broadcast: the megaphone Message every agent in the agents toolbar, shown as soon as one console is open; in the Open Space, the Everyone action.
  • The two switches: Settings > Agents & AI > AI providers & accounts, Inter-agent messaging and, right under it, A message may start the recipient.

How to use it

Agents message each other on their own through the MCP tools; you set nothing up. To intervene:

  1. Open Organization, pick a member, read the thread, type a Subject and a body, Send. Your message follows the same path and gets the same receipts as an agent's ("Handed over as soon as this member is between turns"; an offline member keeps it until it comes back).
  2. To stop one agent: Pause coordination on its row freezes it in both directions, nothing deleted; Resume coordination hands over what was held. Cancel pending erases the messages nobody has read yet (confirmed, irreversible; read messages are kept).
  3. To broadcast: click the megaphone, every open agent is pre-selected as a chip with its live status, untick the ones you do not want to interrupt, type and Send the message to everyone. Each copy carries a header naming the other recipients and forbidding relays.
  4. To let mail reach a member that has no console: turn on A message may start the recipient. From then on a message queued for an offline member opens its console in the background, in its own project, without moving anything on your screen: resumed on its previous conversation when one is recorded and session restore is allowed, fresh otherwise. The agent reads its inbox first, then the notice is handed over as soon as the console is ready.

Without the switch, the shortest path is still to start the recipient yourself: its brief tells it the inbox is waiting and it reads it before asking you for a task.

Settings

  • interAgentMessaging (global, Settings > Agents & AI > AI providers & accounts > Inter-agent messaging, default on): off refuses agents_send and agents_reply and stops queued agent messages from being written into any console. Nothing is deleted; your own messages from the Organization panel still go through, and the panel shows a banner saying messaging is off.
  • agentMailWakesRecipients (global, same place, A message may start the recipient, default off): a queued message may start the recipient's console when it has none. Greyed out and without effect while interAgentMessaging is off. Starting a console costs a model turn, which is why it is opt-in.

Agent tools (MCP)

  • agents_list_live: the project roster with each member's live state, unread count, current ticket and what it says it is doing. The only tool of the family usable without an agent identity.
  • agents_send: write to one member, several, or * to broadcast; returns the message id and the state of each recipient's console. For a recipient with no console, the answer says whether the app is opening one (switch on) or the message waits until that agent runs again (switch off). Refuses a duplicate of a subject already sent to the same member within the hour and still unanswered.
  • Another project of the account (since 2026-10-02): agents_list_live({ project }) lists the agents of a sibling project and agents_send({ project, to, ... }) writes to one of them, for example to report a bug found in a shared library to the agent that maintains it, without opening a console there or filing a duplicate ticket. The target project must be open in the desktop (its mailbox lives in its folder). Same rate limits, same ceilings, same pause (a member paused in its own project cannot write elsewhere, and what it already sent is held too). * is refused across projects. The message is stored in the recipient's project; the recipient sees the sender as "name · project", and agents_reply sends the answer back to the sender's own inbox. agents_message_status finds a message sent to another project by its id.
  • agents_message_status: where a sent message stands per recipient (queued, delivered, read, accepted, rejected, replied) and what to do about it.
  • agents_read_inbox: read the caller's mailbox (unreadOnly, threadId, limit); a peek mode marks nothing. Reading is what marks a message read, with one exception since 2026-09-15: a message that comes back in a batch before any notice announced it in the console is not marked read, is counted as unannounced in the response, and stays unread until the agent replies to it, acknowledges it, or is reminded of it by a notice when its console is next free. agents_read_inbox({ messageId }) reads one message alone, whatever else is waiting, and gives it its read receipt: the way to read a message named by a notice or listed as unannounced; unreadOnly, threadId and limit are then ignored.
  • agents_reply: answer in a thread and mark the parent replied.
  • agents_ack: accept, decline or report done, with a note.
  • agents_report_status: declare a work phase, a blocker or a rate limit.

The sender is never an argument: the server stamps it from the calling CLI's identity. Since 2026-09-15 that identity is also recovered from the desktop's own record of which console the CLI runs in, so an agent whose shell or CLI dropped the environment variable still reads its mail and reports its status; a server started by hand outside a console stays anonymous.

Providers

All providers: the tools live on the AgentsRoom MCP server registered with every agent. A message from a Claude Code agent to a Codex agent is an ordinary message. The startup reminder reaches every provider (through the system prompt when the CLI has one, through the first message otherwise), and a wake resumes the previous conversation only on providers that know how to resume; the others get a fresh console.

Mobile

Broadcast only. The mobile companion has the same Message every agent megaphone above the agents list; the fan-out runs on the desktop, with the same header and per-recipient report. The Organization panel and the two switches are not on the phone: the mailbox addresses consoles of the desktop machine, and a wake opens a console there. The phone simply sees the woken agent come back to activity through the usual sync.

Limits

  • No blocking wait: an agent sends, finishes its turn, and is woken by the notice when the answer arrives.
  • A message is never delivered into an agent engaged in a live team run; the run's own delivery owns that console.
  • Agent-to-agent sending is rate limited on purpose, so a chain of agents relaying each other cannot become a message loop.
  • A broadcast never boots a console: agents without a live session are simply not recipients. An agent still starting keeps its copy queued.
  • A wake is bounded: it respects your plan's parallel-agent limit (checked silently, no upgrade prompt, the message just keeps waiting), it is attempted at most once every ten minutes per member (so a console that dies at boot is not relaunched on every sweep), and it never starts the assistant agent. The startup reminder is not added to a console offloaded over SSH, where the mail tools are not connected.
  • The greeting a fresh console ends with ("what would you like to work on?") no longer holds the mailbox: during the first 90 seconds after the CLI is ready, a question written in prose counts as free for delivery. A prompt owned by the CLI (permission, model choice) still blocks it.
  • A message is also held while you are typing in the recipient's console (its prompt or the message box), so it never merges with your half-written line: it goes out once you send or clear what you typed, and at the latest 30 seconds after your last key, so a line left half-typed only delays the mail. This applies even when that console is not on screen.
  • Messages never become backlog tickets and are never promoted to the project memory automatically.
  • Two members with the same name are told apart by a short id shown next to duplicate names.

Common questions

  • What if the recipient is offline? The message waits, shown as waiting; it is delivered the next time that member is in a state where reading it makes sense. With A message may start the recipient on, the app opens that member's console in the background instead of waiting for you.
  • My teammate is offline. Will my message start it? Only if A message may start the recipient is on (Settings > Agents & AI > AI providers & accounts); it is off by default because a console start costs a model turn. When it is on, the console opens in the background on the previous conversation when there is one, the agent reads its inbox first, and the sender's agents_send answer says the launch is under way. If the member is still reported offline several minutes later, the launch failed (missing CLI, exhausted quota, parallel-agent limit) and only you can fix it. When it is off, start the teammate yourself: it reads its inbox before asking you anything.
  • Can a message interrupt an agent mid-work? No. Delivery is held while it thinks or waits on you, and only a short notice lands.
  • A message from another agent got glued to what I was typing and went out with it. Fixed on 2026-09-26: delivery now waits until you send or clear your line (30 seconds at most after your last key).
  • Can an agent write to an agent of another project? Yes, with the project argument of agents_send (and agents_list_live to find the recipient), as long as both projects belong to your account and the target is open in the desktop. The answer comes back to the sender's own inbox. Adding text to another project's existing ticket is still not possible: a message to the agent that owns it is the way to pass the finding along.
  • How is this different from Agent Teams? Lifetime. A team run's members are ephemeral nodes addressed by role and their inbox dies with the run; messaging is between permanent saved agents addressed by name, for as long as the project exists.
  • Can I turn it off? Yes, one switch in Settings (see above), plus Pause coordination per member.
  • Does the identity survive a model or provider change? Yes, the member is the saved agent, not the session.
  • My message says delivered or queued, but the agent never got it. Fixed in 1.175.0. Before, a message that arrived while the recipient was already reading its inbox for another notice was marked read together with that batch, so it left the unread list and was never announced, and the sender saw it as read and ignored. Now only a message the agent was told about, or read on its own, gets a read receipt; the others stay unread and are announced when the console is free. If a message still looks stuck, agents_message_status with its id says where it stands, and the recipient can call agents_read_inbox with unreadOnly.
  • An agent launched by another agent says it has no identity and cannot read its inbox. Fixed in 1.174.0. Some environments (a shell profile or a CLI that rebuilds the environment of its MCP servers) dropped the identity variable, so agents_read_inbox, agents_ack and agents_report_status refused. The identity is now also found from the console the CLI runs in. capabilities_get with the runtime topic shows which identity an agent has.

Related