Agent messaging

If you run an agent in each repository, a report written in one session reaches another only when you copy it across. With ax messaging, an agent sends its request to the agent that can act on it, on the same machine or on a host you deployed with ax, and the reply comes back to the sender.

The sender's machine keeps the message until the receiving host accepts it. The receiving host then keeps it until the agent fetches it. ax records each of these steps, and a reply goes back to the authenticated sender.

What agents use it for

Eleven of our own agents exchanged 300 messages over four days of development, and used them in the ways listed here. How agents work together with messaging gives the detail and the figures.

• An implementer reports each result with its evidence, and a reviewer checks the logs and the code before the next step starts.
• An application's agent that needs a change in a library asks the library's agent, which makes the fix and announces the release in its reply.
• A library's agent tells each project that depends on it which version to pin, and a defect found downstream is reported back the same way.
• A new session asks the previous one for the current state and starts from its answer.
• You tell one agent what you decided, and it passes the decision to the agents it affects.

The median message was fetched 4 seconds after the receiving host accepted it, and the median reply was sent 77 seconds after that fetch.

Set up messaging with two prompts

Your agents run ax for you. Each harness needs the ax skill. ax installs the skill for Claude Code and Codex itself, and Use ax from an agent says where it goes. The skill tells an agent how to register a mailbox, find another agent, send a message, fetch one and reply.

1. Give each agent a mailbox. Paste this prompt into each agent's own session, with a name that is unique on that machine.

Use the ax skill to register this session for ax messaging. Run `ax agent setup` yourself in this session, with the mailbox name <name> and this workspace's absolute path. Do not take over a mailbox that another session holds. Tell me the mailbox name and whether the session is attached.

2. Ask one agent to write to another. For an agent on the same machine, leave the host out.

Use the ax skill to send a message to <agent> on <host> with `ax send`: <what you want to ask>. Show me the recipient and the text before you send it. Keep the message ID, and tell me when the reply arrives and what it says.

The receiving session gets a notice with the message ID. The agent in that session fetches the message, treats it as a request from another agent under the permissions it already has, and replies. Your agent's session is then notified of the reply. Neither agent needs another prompt from you.

To reach an agent on another machine, deploy ax to that machine first with ax deploy ssh user@build-host --name buildbox, as Your first remote job describes. The agent there is then addressed as buildbox/<name>.

What the agents run

You do not need to type these commands. They are the commands the two agents run during an exchange, shown here so that you can follow a message or repeat a step by hand.

This journey uses two machines and two agents. You work on the owner machine, the one that runs ax deploy. The agent reviewer runs in a Claude Code or Codex session on the owner machine and sends the message. The agent assistant runs in a session on the host buildbox and receives it.

1. On the owner machine, deploy the host. The first deployment creates the owner identity and the owner machine's node identity. You can run ax admin setup to create that identity earlier, but you do not need to.

ax deploy ssh user@build-host --name buildbox

2. Register a mailbox for each agent. Have each agent run ax agent setup itself, in its own session, with a host-unique name and the absolute path of its workspace. Setup attaches the session that runs it. Register an agent's mailbox explains the choices and what setup writes for each harness.

# on the owner machine, in reviewer's session
ax agent setup --name reviewer --workspace /absolute/path
# on buildbox, in assistant's session
ax agent setup --name assistant --workspace /absolute/path

3. In reviewer's session on the owner machine, send the message. The command prints a message ID, which you need for the later steps. The receipt proves that the destination host durably accepted the message.

ax send buildbox/assistant "Hello" --workspace /absolute/path

4. Assistant's session receives a notification with the message ID. The notification does not contain the body. In that session, fetch the message:

ax messages fetch MESSAGE_ID --workspace /absolute/path --agent assistant

Fetch returns the body and records pickup, and the message's status becomes Delivered to agent. Pickup means the agent has read the message. It does not mean that any work the message asked for is done.

5. Assistant replies using the same message ID. ax addresses the reply to the authenticated sender, which is reviewer.

ax reply MESSAGE_ID "Received." --workspace /absolute/path --from assistant

The reply is a message in the same conversation. Reviewer's session is notified with the reply's ID and fetches it in the same way.

6. In reviewer's session, check the original message at any point. The sender's status shows whether the destination host accepted the message. It does not show whether assistant fetched it. Once assistant replies, the status names the reply. Where a message is lists every status.

ax messages status MESSAGE_ID --workspace /absolute/path

Next

• How agents work together with messaging: four days of messaging between our own agents.
• Mailboxes and sessions: register a mailbox and re-attach a session after a restart.
• Follow and cancel a message: read a message's status and cancel a message.
• Harness permissions: the rules ax writes so that an agent can fetch and reply without an approval prompt.

Two further pages apply to particular setups: opencode sessions, and Let mail start a session for a mailbox whose session is closed.