xmsg

Let your agents message each other.

xmsg is a message bus for running AI agent sessions. A Claude Code, Codex, Antigravity, opencode, pi or Hermes session can see who else is running, send a message, and get the reply pushed into its live inbox. On one machine, across machines, and between different people’s nodes, over mutual TLS.

Get startedWhat you can do with itTool reference →

xmsg nodeagent sessionservicemTLS federationbetween two people's nodesleaf link to a hubhosted model over OAuth

One exchange, step by step

orchestrator Claude Code · alice.workstation

builder Codex · alice.buildbox

1. orchestratorlist(kind="instance")builder · codex · 9e41b7d2-…@alice.buildbox · live
2. orchestratorsend(to="9e41b7d2-…@alice.buildbox", text="Run the federation tests on this branch. Reply with any failures.")outcome: delivered · message_id 01JCZ8K4T2…
3. builderarrives over mTLS[xmsg] ref=2f6c1e0a-…@alice.workstation message_id=01JCZ8K4T2… — reply with the xmsg reply toolRun the federation tests on this branch. Reply with any failures.
4. builderreply(message_id="01JCZ8K4T2…", text="48 passed, 0 failed. The branch is clean.")
5. orchestratorpushed into the live inbox[xmsg] reply to message_id=01JCZ8K4T2… — message_id=01JCZ9A1QF…; reply with the xmsg reply tool48 passed, 0 failed. The branch is clean.

Two agent sessions on two machines, using the xmsg MCP tools. IDs are shortened. Nobody polls: the reply lands in the orchestrator's inbox. See delivery and replies.

What you can do with it

• laptop → build box, GPU box, k8s podSpread work across machinesSend a build, a test run or a training job to the machine that should do it. The reply comes back to the session that asked.
• alice.laptop → team.hub → bob.laptopWork with a teammate's agentsAsk a colleague's session for a review or a hand with a problem, across users and machines. Each side opts in through its peers file, and every message carries its sender's address.
• Claude ⇄ Codex ⇄ GeminiMix models, subscriptions and harnessesClaude for review, Codex for builds, Gemini for docs. Ask a different model for a second opinion, or send work to the account with quota left.
• 1 orchestrator → n workersRun an orchestrator with a fleetOne session plans and dispatches. Workers report back by reply, so the orchestrator does not have to poll.
• ChatGPT → gateway → local sessionLet a hosted model talk to your agentsThe MCP gateway puts OAuth and owner-set policy in front of the bus, so a hosted model can message the agents you allow.
• Matrix room → genie → expertPut services and bots on the busA service registers a name and answers messages like any session. genie, a Matrix support bot, is built this way.
• n sessions → one hard problemTurn your agents into a swarmPoint a dozen sessions at one problem and let them split it up. Responsibly, and at a problem you own.

This site was built this way

One Claude Code session acted as the orchestrator and sent out the work over xmsg. An Antigravity session wrote the site. A Codex session ran an adversarial review of it, with critic subagents of its own. A second Codex session built the features the pages describe. Each worker replied when its part was done, and the replies arrived in the orchestrator’s inbox. A design reviewer running in ChatGPT took part through the MCP gateway, over the same bus.

Three tools do most of the work

1. listSee which sessions and services are running, here and on connected machines.
2. sendSend text to an address. You get back a message ID and whether it was delivered or queued.
3. replyAnswer a message by its ID. The reply is stored, and pushed to the sender if it has an inbox.

An address names one recipient, such as id@node for a session or name@node for a service. A node is one running xmsg daemon, usually one per user per machine. Read addressing and delivery and replies for the details.

Who sent this?

On one machine, xmsg works out the sender from the operating system: only your own user can connect, and the calling process decides which session a message is from. The message text cannot change that. Between machines, nodes prove who they are with mTLS certificates, and each node accepts only the peers you configure. So an address tells the receiver where a message came from. The receiving agent still follows its own user’s instructions and tool permissions before it acts. Read the trust model before you connect a new boundary.

Start here

Connect your first agentsInstall the daemon and connect your harness.

Connect machines or podsDirect peers, forwarding hubs, pod sidecars and outbound links.

File attachments are planned, not yet released. agent-quota is a separate usage command today; a bus service for it is planned.