Agents messaging each other
In the Agent HUD release, Claude Code, Codex, Antigravity and DeepSeek Harness pass each other single messages, never their conversations, over its MCP server.
When Claude Code finishes a change, it can ask a Codex session to review it and get Codex's answer back, or start a new session and hand the task over. Agent HUD already sees every session on your Mac, so it carries messages between clients that cannot reach each other on their own. You watch it happen on the HUD: each message flies as a paper plane from the sender to the receiver.
Agent messages are in the release only, free to use, and stay on your Mac: they need no Agent HUD Remote. A build from source has the HUD tools, but not messages.
A message, not the conversation
A message carries what the sending agent writes, under a label with its agent and session title. Nothing else of either session goes across: not the conversation so far, not the files it read, not its tool calls. What comes back is as narrow: the receiver's reply, or the last reply of the turn the message began.
So when two agents work on one project, the project itself is their shared context. The sender says what it needs, such as "Review the change on this branch", and the receiver reads the code, the diff and the tests for itself, in its own session. Neither takes in the other's conversation.
Which agents take part
| Agent | Sends | Receives | Can be started |
|---|---|---|---|
| Claude Code | ✓ | ✓ | ✓ |
| Codex | ✓ | ✓ | ✓ |
| Antigravity | ✓ | ✓ | ✓ |
| DeepSeek Harness | ✓ | ✓ | — |
Cursor and other MCP clients have the HUD tools, but not messages: Agent HUD cannot tell which of their sessions is calling, and has no way to deliver into them.
Messages go between main sessions on the same Mac, never to sub-agents. A receiving session needs a way in:
- Claude Code: Agent HUD's plugin for Claude Code, loaded in that session, with Send messages on in its row in Settings → Agent plugins.
- DeepSeek Harness: Agent HUD's plugin for DeepSeek Harness, running in that session, with Send messages on in its row. A Harness session sends through the same plugin.
- Codex: a Codex app or command line with the thread open. If none has it open and the Codex app is installed, Agent HUD opens the thread there; otherwise the message waits in Codex's queue until the thread is opened.
- Antigravity: its running local service.
Turn it on
In Settings → Agent plugins, add HUD tools to each agent that should send messages. See Connect an agent.
Under Agent tools, turn on Let agents message each other. It is off until you turn it on.
Start a new session in the agent. Sessions load their tools when they start, so one opened earlier does not have the message tools.
Then ask in plain words, for example "Ask the Codex session on this repo to review the change, and wait for its answer."
How a message travels
The sender sends
The agent finds the receiving session with list_sessions and sends with send_message. The call returns at once: the message is queued, or refused with the reason.
It waits for an idle session
The message waits in the receiving session's queue and goes in as a new turn once that session is idle. It never interrupts a turn in progress.
The receiver sees who wrote
The message starts with a line naming the sender and a message id, such as [Agent HUD · from Codex · Fix login · m-8f2c], and ends with a line saying how to reply.
The answer comes back
The receiver replies with send_message, and the reply reaches the sender's session as a new turn once it is idle. A receiver without Agent HUD's tools simply answers; the sender then reads that answer with get_message, from what Agent HUD already collected about the session. Reading an answer never wakes the other session.
An agent can also open a new Claude Code, Codex or Antigravity session with start_session. It starts in a folder you already use with that client, or in a task folder of its own, and in the client's desktop app where one is installed.
The paper plane
- The sender folds its message into a paper plane and flies it to the receiver's mark on the HUD. In Notch mode the two agents lean out on either side of the notch; in Simple and Dynamic mode the plane flies from one logo to the other.
- The answer flies back once, when it arrives.
- A refused message falls halfway.
- Several messages in a row between the same two sessions fly as one plane with a number on it.
- With Reduce Motion on in macOS, nothing flies: a closed envelope fades in beside the sender, then an open one beside the receiver.
Settings and safeguards
| Setting | What it does | Default |
|---|---|---|
| Let agents message each other | Lists the message tools to agents with HUD tools | Off |
| Send as me | Sends messages as your own words, with no label saying an agent sent them | Off |
| Passes in a row | How many messages agents may pass back and forth with no word from you before they wait for you: 3, 5, 10, 20, 50 or No limit | 10 |
Send as me
With Send as me on, the receiving agent takes a message as yours and may act on it, approving deletions or releases among other things. It does not know an agent sent it, so it answers in its own session, and the sender reads that answer with get_message.
- A word from you resets the count. Type anything in any session of the chain, and the passes start from zero again. Starting a session counts as a pass; reading an answer does not.
- The words are kept only while they are delivered. Agent HUD records who sent a message to whom, a fingerprint of its words and where the answer will be, and keeps that record for a week.
- No impersonating your phone. A message that starts with
[Agent HUD · iPhone], the tag of words you send from your phone, is refused. - Text is never cut. Your agent's own client may shorten a long answer it reads back.
When a message does not arrive
| What the sender is told | What to do |
|---|---|
| Agent messages are off | Turn on Let agents message each other, then start a new session. |
| Agent HUD's Claude Code plugin is not loaded in this session | Install the plugin in Settings → Agent plugins, then run /reload-plugins in that session. A session closed or paused by the Claude desktop app cannot receive. |
| Agent HUD's DeepSeek Harness plugin is not running in this session | Install the plugin in Settings → Agent plugins. |
| Codex keeps it queued | No Codex app or command line has the thread open. Open the thread in Codex. |
| These agents have passed messages N times in a row | Type a word in any of their sessions, or raise Passes in a row. |
| Agent HUD could not tell which session is calling | Only Claude Code, Codex, Antigravity and DeepSeek Harness sessions can send. |
Last updated