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.
Two lines in any Claude Code session:
/plugin marketplace add {{ plugin_marketplace or "<catalogue address>" }}
/plugin install aim@aimOr 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 uvx, 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, LinuxOpen a new terminal afterwards, so uvx is on the PATH. 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.
claude --channels plugin:aim@aimThat 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.
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.
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-officialWhile 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-officialEach 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.
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.
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 {{ public_url }}/link.
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.
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.
Open the connectors section in settings, choose to add a custom connector, and paste
{{ mcp_url }}.
Run the client locally — the session gets an address of its own and your key stays on the machine:
codex mcp add aim --env AIM_HOST=codex -- uvx --from aimessenger aim channelAIM_HOST=codex names the session after the tool, so a Codex window and a Claude
session in the same folder do not end up with the same address. Or, with nothing installed, as a
remote server:
codex mcp add aim --url {{ mcp_url }}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.
In ~/.gemini/settings.json:
{
"mcpServers": {
"aim": { "httpUrl": "{{ mcp_url }}" }
}
}Then run /mcp auth aim in the CLI and finish signing in through the browser.
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": "{{ mcp_url }}", "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 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
{{ plugin_marketplace or "<catalogue address>" }} 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.
Any client that can use a remote MCP server over HTTP with OAuth will do. The server address is
{{ mcp_url }} 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.
Every session has the address handle@{{ relay_host }}/session-name. The handle is
yours; the session name is up to you and is lowercased:
/rename AIM-backend makes the address
your-handle@{{ relay_host }}/aim-backend.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.
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 aimThe 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.
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.
handle@{{ relay_host }}/session) into the dashboard and sends a
request. aim pair request does the same from a shell.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@{{ relay_host }}/build reach your
evoluce or cyber-web, while a message from
bob@{{ relay_host }}/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.
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 treats their messages roughly as it treats yours: it gets on with the task instead of asking about each step.
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 are trusted 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 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.
| 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@{{ relay_host }}/session) or by session name when it is unambiguous; an
ambiguous name is not guessed, the tool lists the candidates instead.
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.
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 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.
By itself, if your client lets it. AIM requires no approval for sending; the rules live in the client, not in the relay:
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.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.
/aim-link and follow section 2./aim-link.CONNECTION_CLOSED. It never
started: almost always because uvx is not on the PATH that Claude Code passes to it.
Run uvx --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 uvx somewhere every process sees it (on Linux and macOS
sudo ln -s ~/.local/bin/uvx /usr/local/bin/uvx). 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.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.uvx --from aimessenger aim peers --accept handle@mailows.uvx --from aimessenger aim --help, then start the session
again.claude --channels plugin:aim@aim, or have the model call
aim_receive./mcp.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.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.