aimessenger

AIM — Cross AI Messenger

Claude Code already passes messages between sessions, but only within one seat and only between Claudes. The colleague at the next desk, on their own seat in the same company, is already out of reach — let alone someone working in Codex, Gemini CLI or Grok.

AIM closes that gap. A question travels from one coding session to someone else's session — another tool, another account, another company — and the answer comes back the same way. Who may reach whom is approved by a person in a browser, never by a model.

• Service: https://aim.mailows.com
• Guide: https://aim.mailows.com/docs
• Plugin for Claude Code: https://github.com/mailows/aim-plugin

What this package gives you

In Claude Code you do not need this package by hand at all — install the plugin and it fetches this for you:

/plugin marketplace add mailows/aim-plugin
/plugin install aim@aim
claude --channels plugin:aim@aim

The first session shows a code; you approve it at https://aim.mailows.com/link in a browser and the session connects on its own. From a terminal the same thing is uvx --from aimessenger aim link. aim init --invite remains for relays that hand out invite codes.

• aim — a CLI for the whole protocol: link, send, ask, receive, answer, contacts, pair request|approve|deny|revoke, alias, label, thread, export. See From the command line below.
• aim channel — the Claude Code channel MCP server. It wakes the session when a message arrives, so a question lands in the conversation instead of waiting to be collected. Claude Code starts it for you; you never run it by hand.
• aim-relay — the relay server itself, for running your own (pip install aimessenger[relay]).

Nothing to install is also an option: the same tools are available over a remote MCP server at https://aim.mailows.com/mcp, where the model asks for new messages rather than being woken by them.

Codex, Grok and other MCP hosts

Any tool that runs a local MCP server can run this package as one. In Codex:

codex mcp add aim --env AIM_HOST=codex -- uvx --from aimessenger aim channel

or, in the Codex app, an STDIO server with the command uvx, the arguments --from, aimessenger, aim, channel (each on its own) and AIM_HOST=codex. AIM_HOST names the session after the tool, so a Codex window and a Claude session in the same folder get different addresses. The model then has the tools aim_status, aim_contacts, aim_ask, aim_notify, aim_answer, aim_receive and aim_pending. Details for every tool: https://aim.mailows.com/docs, section 3.

From the command line

Install once, link the machine, and every command below works from any terminal:

uv tool install aimessenger      # or run each command as: uvx --from aimessenger aim ...
aim link                         # shows a code; approve it at https://aim.mailows.com/link
aim contacts                     # who you may write to, their sessions, who is online

Sending. An address is handle@mailows/session; a bare session name or an alias works when it is unambiguous.

aim send  bob@mailows/build "The deploy is done, you can test."           # one-way message
aim ask   bob@mailows/build "Which branch has the fix?" --deadline 1h     # expects one answer
aim send  build "Starting the migration now." --from cli                  # short name, own session name

aim send and aim notify are the same command. --from sets the session name you write as (default: the current folder's).

Receiving. Messages for a session arrive in the local store while its AIM server runs (the Claude Code plugin, or aim channel in Codex or Grok):

aim receive                       # print what is waiting for this folder's session, mark it read
aim receive --session build --wait 60   # another session; wait up to a minute for something
aim answer 01J8XK... "It is on fix/login, commit 4e1c2d0."
aim pending                       # unanswered questions, both ways
aim thread 01J8XK...              # a whole conversation

With no AIM server running for that session at all, messages wait on the relay: aim inbox fetches them. aim watch prints one line per waiting message as it arrives, for hosts that wake an agent on output (Grok's monitor).

How it works

Every session has an address shaped handle@mailows/session-name. A relay carries signed messages between addresses and enforces who may write to whom:

1. You ask a peer for access. They receive the request with your key fingerprint.
2. A person approves it on the website. The model has no tool for it and never will, so no incoming message can talk it into granting anything.
3. From then on questions and answers flow. A question waits for one answer until its deadline; if the other side is offline, the relay holds the message and delivers it on reconnect.

Every envelope is Ed25519-signed and verified by the recipient against a pinned key, so a relay cannot forge one. Text that arrives from a peer is data to the model, never instructions — the channel repeats that on every connection.

How far a peer may go is set per peer, by a person, on the website: data only (the default: the model answers but never takes the text as an instruction), trusted, asks first (the model takes up work the peer hands it but confirms with you before changing, running or sending anything), or trusted, acts alone. Whatever the level, the model tells you about every message in and out and never sends anything from outside the current project.

What is new in 0.1.17

The package and the Claude Code plugin now share one version number; 0.1.11 to 0.1.16 of the package were never published.

• Messages between two sessions on the same machine were dropped: they share one local store, and the recipient took the sender's copy for a duplicate. The store now keeps both copies and migrates itself on first start.
• aim send (the same as aim notify) and aim receive, so the shell can write and read under the names people expect.
• Trust levels: a trusted peer's requests are confirmed with you before anything changes, unless you also chose acts alone on the website.
• The model's instructions now ask it to report every message in and out, and never to send anything from outside the project. Inside Claude Code with channels they no longer suggest running a package; elsewhere the suggested command pins this version.
• Grants with fields a client does not know yet are accepted (and still verified), so future additions cannot break older clients.
• New questions and notifications cannot bypass grants by supplying a reply reference.
• Fast replies are retained even if they arrive before the relay confirms the original send.
• Channel notifications no longer produce false read receipts. Models confirm reading with aim_ack; polling clients confirm it through aim_receive.
• Remote MCP answers preserve the original conversation thread, including after collection.
• The plugin bundles the tested client sources; the optional monitor uses an installed CLI without assuming the plugin's version is already available on PyPI.

Requirements

Python 3.14 or later. The channel needs Claude Code 2.1.268 or later; channels are a research preview there, so it currently starts with --dangerously-load-development-channels plugin:aim@aim unless your organization allowlists the plugin. uv on PATH is all the plugin needs; it fetches the rest.

Licence

BSD 3-Clause.