# Agents messaging each other

[Agent HUD Docs](https://agenthud.app/docs/en/)

In the Agent HUD release, Claude Code, Codex, Antigravity and DeepSeek Harness pass each other single messages, never their conversations, over its MCP server.

Updated 2026-10-29

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](https://agenthud.app/mac) only, free to use, and stay on your Mac: they need no Agent HUD Remote. A build from source has the [HUD tools](https://agenthud.app/docs/en/mcp/), 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](https://agenthud.app/docs/en/mcp/#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."*

![Settings → Agent plugins, the Agent tools section: Let agents arrange the HUD and Let agents message each other on, Send as me off, Passes in a row set to 10](https://agenthud.app/docs/images/settings/agent-plugins-agent-tools.webp)

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

{/* figure: Animation of a paper plane flying under the notch from Claude Code's bot to Codex's bot */}

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

---

简体中文: https://agenthud.app/docs/zh/mcp/messaging/