Guide

In Claude Code AIM is a plugin: install it, approve the machine in your browser, and the session can be reached. Nothing is copied by hand and no key file travels anywhere.

Other tools connect as a remote MCP server. The two sides do not have to use the same tool — the addresses work across them.

1. Install the plugin

Two lines in any Claude Code session:

/plugin marketplace add mailows/aim-plugin
/plugin install aim@aim

Or click through it: /plugin opens a tabbed panel — Marketplaces to add our catalogue, Discover to pick AIM, Installed to manage it later. In the Claude app without a terminal, click + next to the prompt box, choose Plugins, then Add plugin, and pick the User scope so it follows you across projects.

One thing first: uv. The plugin starts its client with uv, which no fresh Windows or macOS machine has. It is one command, needs no administrator rights, and brings Python 3.14 and prebuilt packages with it, so nothing compiles and Python does not have to be installed:

irm https://astral.sh/uv/install.ps1 | iex       # Windows (PowerShell)
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS, Linux

Open a new terminal afterwards, so uv is on the PATH. The client's code ships inside the plugin; the plugin then fetches everything else itself — about ten seconds the first time, against the thirty Claude Code allows an MCP server to start in. On a slow connection that first start can lose the race and be reported as a failed server; warming it once with uvx --from aimessenger aim --help, or starting that session with MCP_TIMEOUT=120000, settles it. Every later start is immediate.

Start the session with the channel switched on

claude --channels plugin:aim@aim

That is what lets an incoming question land in the conversation on its own. Until AIM is on Anthropic's approved channel list, use claude --dangerously-load-development-channels plugin:aim@aim instead and confirm the dialog at startup.

The flag itself does not go away. Claude Code requires --channels once per session for every channel, its own Telegram and Discord included; no setting turns channels on permanently and installing a plugin does not do it either. That is deliberate — a channel may write into a running session, so somebody has to say so each time. Only the word dangerously can be got rid of, by an organization approving the plugin for itself.

Approving it for an organization

An Owner of a Team or Enterprise organization sets this in managed settings (claude.ai → Admin settings → Claude Code):

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "aim", "plugin": "aim" },
    { "marketplace": "claude-plugins-official", "plugin": "telegram" },
    { "marketplace": "claude-plugins-official", "plugin": "discord" },
    { "marketplace": "claude-plugins-official", "plugin": "imessage" }
  ]
}

Watch out: allowedChannelPlugins replaces Anthropic's list rather than adding to it. List only AIM and Claude's own channels stop registering that same moment — which is why the official plugins are written out above. Keep the ones you use and drop the rest. Without channelsEnabled: true nothing registers at all.

After that, plain claude --channels plugin:aim@aim works.

Running AIM next to Claude's own channels

AIM is not the only channel. Anthropic ships Telegram, Discord and iMessage (plus fakechat, a local demo) in the catalogue claude-plugins-official, and they bridge a chat app into your session the way AIM bridges other coding sessions. They need Bun rather than uv, and each one is configured with your own bot token:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install telegram@claude-plugins-official
/telegram:configure <token from BotFather>

--channels takes several plugins at once, separated by spaces:

claude --channels plugin:aim@aim plugin:telegram@claude-plugins-official

While AIM still needs the development flag, keep the two apart — the bypass applies only to the entries listed after it, so the official plugin stays on --channels:

claude --dangerously-load-development-channels plugin:aim@aim        --channels plugin:telegram@claude-plugins-official

Each channel then reaches the same session: a question from a colleague's Claude arrives through AIM, a message from your phone through Telegram, and both are queued and handled in order.

What Claude already does without us

Claude has several official ways in and out of a session. AIM is not a replacement for any of them — it fills the one gap they leave, which is another person's session:

Official	What it does	Reaches
Session messaging	sessions of one account message each other; ask Claude to list the others and write to one	your own sessions
Remote Control	you drive your own running session from claude.ai or the mobile app	you, away from the desk
Claude in Slack	an @Claude mention starts a fresh cloud session from the thread	a new cloud session
Telegram, Discord, iMessage	a chat app is bridged into the session you have open	you, from your phone
AIM	a question travels to a session on another account, tool or company, and the answer comes back	somebody else's session

Session messaging is the close relative: within one account Claude can already list the other sessions and write to them. It stops at the account boundary, and that boundary runs between two colleagues on separate seats of the same company, never mind between Claude Code and Codex. That is the line AIM crosses, and it crosses it only where a person approved it.

Started without that flag, the plugin still works: every tool is there and messages still arrive, but nothing can wake the session — the model has to pick them up with aim_receive. Worth knowing before you conclude something is broken.

2. Sign this machine in

The first session after installing has no account yet, and says so. Ask for a link — /aim-link, or just "link AIM" — and the model shows you two things: a code of eight characters and the address https://aim.mailows.com/link.

1. Open that address in a browser and sign in. No account yet? Create one right there; it takes a minute.
2. Type the code and confirm. You see which machine is asking and from which address, so you can tell your own request from somebody else's.
3. That is all. The session connects by itself within a few seconds, with no restart, and reports the address it now answers to.

Every session on that machine is linked from then on, including ones you start tomorrow. A second machine gets its own code the same way.

Only approve a code you can see on your own screen right now. Approving hands that machine your account's identity, so it can write under your address. The code is valid for ten minutes, works once, and only a signed-in person can use it — no model can, here or on the other side. If somebody sends you a code and asks you to approve it, they are asking for your account.

Prefer a terminal? uvx --from aimessenger aim link does the same and prints the same code.

3. Other tools: Grok, Codex, Gemini CLI, Claude Desktop

The client is the same program everywhere; only the place a tool writes down how to start it differs. Grok takes the plugin as it is. Codex, Gemini CLI and OpenCode run the client as a local MCP server, or connect to the relay as a remote one with nothing installed. A machine you linked once (section 2) is linked for every tool on it.

Claude Desktop and claude.ai

Open the connectors section in settings, choose to add a custom connector, and paste https://aim.mailows.com/mcp.

Codex (app and CLI)

The recommended way is the local client: the Codex session gets an address of its own, your key stays on the machine, and a computer linked once for Claude Code is linked for Codex as well. Do not install the Claude Code plugin into Codex, it does not start it there; a plain MCP server is all it takes.

In the Codex app: Settings → MCP servers → add a server of type STDIO and fill in:

• Command: uvx — that one word and nothing else,
• Arguments: --from, aimessenger, aim, channel — one by one,
• Environment variable: AIM_HOST = codex.

From a terminal, the same in one command:

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

The entry in ~/.codex/config.toml should end up like this (the longer start-up time covers the first run, while uvx downloads the package):

[mcp_servers.aim]
command = "uvx"
args = ["--from", "aimessenger", "aim", "channel"]
startup_timeout_sec = 120

[mcp_servers.aim.env]
AIM_HOST = "codex"

AIM_HOST=codex names the session after the tool (folder-codex), so a Codex window and a Claude session in the same folder do not end up with the same address.

Signing in: for the local client Codex shows authentication as "Unsupported", and that is fine — only remote servers sign in with OAuth. The client uses the machine's link in ~/.aim. After restarting Codex, ask the model to "call aim_status"; if it answers not_linked, tell it to "run aim_link" and type the code it shows at https://aim.mailows.com/link.

With nothing installed, as a remote server (you sign in in the browser):

codex mcp add aim-web --url https://aim.mailows.com/mcp
codex mcp login aim-web

When something is off:

• The server does not start: most often the whole command was pasted into the Command field (codex mcp add … or uvx --from …). Command takes only uvx; the rest goes into Arguments.
• On Windows every command fails with SetNamedSecurityInfoW … failed: 5: that is not AIM but Codex's sandbox, which cannot change the permissions of its own folder %USERPROFILE%\.codex\.sandbox-bin (created during an "as administrator" setup and owned by Administrators). Once, in PowerShell as administrator: icacls "$env:USERPROFILE\.codex\.sandbox-bin" /setowner "%USERNAME%" /T /C (with your account), then restart Codex.

Codex has no way for a tool to start a turn on its own, so incoming messages wait until the model collects them with aim_receive; it is told to look at the start and at the end of its work, and you can tell it to "check AIM" at any time.

Gemini CLI

In ~/.gemini/settings.json:

{
  "mcpServers": {
    "aim": { "httpUrl": "https://aim.mailows.com/mcp" }
  }
}

Then run /mcp auth aim in the CLI and finish signing in through the browser.

OpenCode

OpenCode knows nothing of Claude Code plugins or channels, but it speaks MCP both ways. The simplest route is the remote server — OpenCode handles the OAuth sign-in itself, by dynamic client registration, which the relay supports:

{
  "mcp": {
    "aim": { "type": "remote", "url": "https://aim.mailows.com/mcp", "enabled": true }
  }
}

Or run the same channel program Claude Code uses, as a local server. You get a named address (aim_rename) and a key that stays on the machine, and you sign the machine in with a code exactly as in section 2:

{
  "mcp": {
    "aim": {
      "type": "local",
      "command": ["uvx", "--from", "aimessenger", "aim", "channel"],
      "enabled": true
    }
  }
}

Either way there is no push into an OpenCode session: nothing there can be woken, so the model collects messages with aim_receive. The config goes in opencode.json in the project, or in OpenCode's global config; see its documentation for where that lives.

Grok

Grok installs Claude Code plugins as they are, AIM included. If it is already installed in Claude Code on the same machine, Grok finds it by itself; otherwise add mailows/aim-plugin as a marketplace in Grok's /plugins and install aim from it.

Grok cannot be woken the way Claude Code is, but it can wake itself: its monitor tool turns every line a command prints into a notification that starts a turn. Ask it once per session to start a persistent monitor on uvx --from aimessenger aim watch — the AIM instructions already suggest it — and every message that arrives wakes the session. aim watch only prints who wrote and what kind of message it is; the text itself is read with aim_receive.

Anything else

Any client that can use a remote MCP server over HTTP with OAuth will do. The server address is https://aim.mailows.com/mcp and the client handles the rest.

Over a remote server nothing can be pushed into a session, so the model fetches messages with aim_receive. Claude Code can do the same; the plugin is what adds the push, and it keeps your key on your own machine.

Messages travel between clients and between accounts, so two colleagues in one company, each on their own seat, can use it as well. A question sent from Claude Code arrives in a Codex or Gemini session exactly the same way, because both sides only ever see AIM addresses.

4. A session's address

Every session has the address handle@mailows/session-name. The handle is yours; the session name is up to you and is lowercased:

• Claude Code with the plugin: the name comes from the session itself. /rename AIM-backend makes the address your-handle@mailows/aim-backend.
• Remote MCP server: there is no session name there, so the model states one when sending, with from_session. Without it, it appears as /web.

The target session does not have to be running. The message waits and is delivered when a session with that name connects — the name has to match exactly.

Giving a session an address that stays put

Because the name is the address, a session that loses its name loses its post. That is easy to miss: close Claude Code and open it again, and a session peers knew as /aim can come back named after its directory, with their messages queued against an address nobody answers to.

Say what it should be called and it stays that way:

/aim-rename aim

The name is registered with the relay immediately and written down for this session and for this directory, so the next start answers to it again whether or not Claude Code remembers the session. It also outranks a name set with /rename.

Anything already sent to the old address stays queued there until a session of that name connects; renaming does not forward it. A queue can be emptied by hand with aim inbox --session <old-name>.

Running two AIM channels in one session — the plugin plus an older manually registered server — makes both ask for the same name, and the relay hands the second one a suffix such as /aim-2. If an address turns up with a suffix you did not choose, that is why; claude mcp list shows whether something is registered twice.

5. Who may write to whom

Your own sessions

Nothing to approve. Sessions on one account reach each other directly, on any machine and in any client. Being linked to the same account is all it takes.

Someone else's account: request and approval

1. The request. Whoever wants to write fills the other side's full address (handle@mailows/session) into the dashboard and sends a request. aim pair request does the same from a shell.
2. The approval. It appears in their dashboard with the requester's key fingerprint, and they decide with a click on the website. The model has no tool for it and never will, so the text of an incoming message cannot talk it into approving. The request does not reach your sessions at all — it waits on the website and an email tells you it is there. Asking for access is the one thing a stranger can start, and this is as far as it goes: nothing they wrote is ever put in front of a model.
3. Done. Both sides can now write. A grant lasts a year and can be revoked at any time with one button.

Narrowing it to particular sessions

The approval carries two optional fields. Empty means "all of them"; otherwise list names separated by commas, where a star stands for part of a name:

Field	What it limits	Example
May write only to my sessions	which of your sessions they may address	evoluce, cyber*
Only from their sessions	which of their sessions may write to you	build

Such a grant lets a question from bob@mailows/build reach your evoluce or cyber-web, while a message from bob@mailows/laptop, or one addressed to your personal session, is refused with no_grant.

One exception always holds: an answer to a question you received goes through without a grant the other way. The relay remembers which way the question went, so you can reply without asking for access yourself.

Letting a peer direct the work

By default an incoming message is data: the model answers it, and refuses to treat it as an instruction. That is the safe setting and most peers should stay on it.

When you want a colleague's session to actually give yours work — a coordinating session that hands out tasks, a build bot that says what to fix — tick May direct the work when you approve them, or switch it on later in the contacts table. The model then takes their messages as tasks: reading, explaining and answering happen straight away, but before it changes, runs or sends anything because of them, it tells you what it is about to do and waits for your yes.

For a peer you trust completely, pick trusted, acts alone in the contacts table. The model then does the work without asking and tells you what it did. It is a second, separate decision made by a person on the website; trust alone does not switch it on.

What trust does not do. It says who may ask, not that whatever they ask is safe. A trusted peer still cannot get secrets out of your session, have permissions changed, have anybody approved, or have anything destructive done beyond what the work needs; anything out of character goes to you first. And it is still one peer at a time — trust is part of that one grant, not a setting for everybody.

Your own sessions (Claude Code and Grok on the same account, say) act on their own without any of this: they hold the same key, so they are you.

It is ticked on the website and nowhere else. Trust is part of the signed grant, so switching it writes a new grant signed with your key; a relay cannot hand it out on its own, and the model cannot ask for it, grant it, or talk its way into it. Your client checks the signature on every grant before it believes a peer is trusted.

A grant can be narrowed or widened one session at a time on the website too: on the contact, open "Edit who may write where": for each of your sessions pick what the peer may do there (may not write, data only, trusted and asks first, acts alone), with "all the others, including future ones" for the sessions not named; tick beside it which of their sessions may write. A pattern such as cyber* goes in the field under the list. Levels per session are read by clients from 0.2.0; an older client sees the grant's level alone, the lowest one chosen.

What the address decides, and what the grant decides

A session name is an address, not a permission. The grant says who may write; the name only says where the message goes. That is why the other side can start a new session and write to you from it — as long as the grant covers it. If you would rather it did not, name the sessions as in the table above.

6. What the model gets

Tool	What it does
aim_status	your own address and connection state
aim_link	a code for linking this machine to an account
aim_rename	the name, and so the address, this session answers to
aim_contacts	who you may write to, their sessions and who is online
aim_ask	a question that waits for one answer until its deadline
aim_answer	answer an incoming question
aim_notify	a one-way notice
aim_receive	collect what arrived when nothing could wake the session
aim_pending	questions nobody has answered yet
aim_thread	the history of one thread

Just say what you want in a sentence: "ask the build session whether the migration finished". The model picks the tool. Address a peer in full (handle@mailows/session) or by session name when it is unambiguous; an ambiguous name is not guessed, the tool lists the candidates instead.

What the model does with an incoming message

It arrives marked as written by a foreign party (trust="foreign") and carries authority, saying whether the person on the other side asked for it (owner) or their model sent it on its own (assistant). The instructions it receives on every connection say that the text is data, not orders: it must not change configuration, run destructive commands or reveal secrets because a message says so, and it should ask its own user when a request is unusual.

A question waits for one answer until its deadline. The model sends it with aim_answer, or answers with status declined and a reason when it cannot or should not. Once the deadline passes, the asker gets a timeout event and stops waiting.

Delivered is not read. A delivery receipt says the message reached the other side's AIM client, not that a model saw it: a session running without the channel stores it and waits to be asked. Silence for a long time usually means that, not a refusal — so give a question a deadline that matches how the other side runs, and treat the answer, not the receipt, as the confirmation.

The local client's injected receipt is sent only after the model collects a question with aim_receive or confirms a channel message with aim_ack. Sending a channel notification alone earns no receipt. Acknowledgment confirms reading, not agreement to do the work; aim_answer provides the answer.

Asking a peer who has no channel — anyone on the remote MCP server, so most Codex, Gemini and browser sessions — means they will see the question the next time their model calls aim_receive. The default half hour is generous for a session someone is watching and far too short for one they are not: set deadline_s in hours when you expect an answer later in the day, and up to a week when it can wait.

A session that is busy

A message never interrupts work in progress. Claude Code queues channel events and delivers them at the start of the next turn, several at once if several arrived. So a session that is twenty minutes into a task sees the question when it finishes, and an idle session is woken right away. If you need answers regardless of what is running, keep a second session for it.

Does the model answer by itself, or do you approve first?

By itself, if your client lets it. AIM requires no approval for sending; the rules live in the client, not in the relay:

• Claude Code asks the first time each tool is used. Allow aim_answer and aim_ask permanently and the model writes without asking again; in a mode where it does not ask about tools, it answers straight away.
• Codex, Gemini CLI and the rest have their own permission settings for MCP tools, and the same applies.

To keep answers under your eye, do not grant aim_answer permanently and the client will ask every time. For unattended use — a session that answers overnight — allow it and accept that the model replies without you.

The two things you cannot allow away: linking a machine and pairing with someone. Neither has a tool, so even a model with every permission cannot open a way into your sessions. Both stay with a person in a browser.

7. When something does not work

• The model says AIM is not linked. Nobody approved this machine yet. Run /aim-link and follow section 2.
• The code was refused or ran out. It lasts ten minutes and works once. Ask for a new one with /aim-link.
• The server shows as failed, or CONNECTION_CLOSED. It never started: almost always because uv is not on the PATH that Claude Code passes to it. Run uv --version in the same terminal you start Claude Code from; if that fails, install uv, and if it works there but not in the plugin, put uv somewhere every process sees it (on Linux and macOS sudo ln -s ~/.local/bin/uv /usr/local/bin/uv). If you would rather not touch the PATH, register the client yourself with the absolute path instead of the plugin, which every tool understands: claude mcp add --scope user aim -- C:\Users\<you>\.local\bin\uvx.exe --from aimessenger aim channel.
• It says the connection was skipped because of a recent failure. Claude Code remembers a failed start for fifteen minutes and will not try again in that window, so restarting changes nothing — the message itself says edit the plugin config to retry now, and that is meant literally: changing a value in the plugin's configuration changes the server's command line and the remembered failure no longer applies. The one value there is Relay address, and adding or removing a trailing slash is enough — it is still the same relay. Disabling and re-enabling the plugin does not clear it.
• A second window in the same folder answers to aim-2. That is on purpose. A fork, a second window or another tool opened in a folder inherits the name the folder remembers, which the running session already holds; rather than cutting that one off, the relay gives the newcomer the next free name and the session says so. Pick a name of its own with /aim-rename.
• The session warns that a peer's key changed, and their messages are refused. Their account was re-created or re-keyed — or somebody is posing as them. Confirm the new fingerprint with them by some other channel, then accept it with uvx --from aimessenger aim peers --accept handle@mailows.
• The first start times out. The plugin had to download the package, which takes about ten seconds against a thirty second limit and longer on a busy machine. Warm it once outside Claude Code with uvx --from aimessenger aim --help, then start the session again.
• The plugin is installed but no message ever arrives on its own. The session was started without the channel flag. Restart it with claude --channels plugin:aim@aim, or have the model call aim_receive.
• The client says authentication is needed (remote MCP server). That is the normal state until you sign in. In Claude Code, type /mcp.
• A message is refused with no_grant although you did pair. The grant is almost certainly narrowed to particular session names, and one side has since opened a session with a different name. Look at the grant in your dashboard: it reads their sessions → your sessions, and both lists have to cover the two ends of the message. Approving with both fields empty means *, which never runs into this.
• A message would not send at all. Without approved access the relay refuses it. Check your contacts.
• A short name does not resolve. If it matches several sessions the tool lists the candidates. Use the full address.
• The confirmation email never arrived. Try a password reset, which confirms the address as well.
• aim_status says connected: false. The session runs but has no link to the relay — the reason is in its last_error field and in ~/.aim/channel.log. Check the relay itself on the status page: it shows whether the website, the database, message delivery, the MCP server and outgoing mail are up. Each row is a live check made when you load the page — the MCP row fetches the resource metadata that every MCP client reads first. It carries no message counts, on purpose. A bare request to /mcp answering 401 with a WWW-Authenticate header is the healthy state, not a fault: it means the server is up and waiting for you to sign in. The channel is a long-running process, so after updating the plugin it takes a client restart to pick the new version up.