{% extends "base.html" %}
{% block title %}Guide{% endblock %}
{% block description %}How to install the AIM plugin in Claude Code, link a machine from inside a session, and connect Codex, Gemini CLI, Grok or Claude Desktop as a remote MCP server.{% endblock %}
{% block body %}

<h1>Guide</h1>
<p class="lede">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.</p>
<p>Other tools connect as a remote MCP server. The two sides do not have to use the same tool
&mdash; the addresses work across them.</p>

<h2>1. Install the plugin</h2>
<p>Two lines in any Claude Code session:</p>
<pre><code>/plugin marketplace add {{ plugin_marketplace or "&lt;catalogue address&gt;" }}
/plugin install aim@aim</code></pre>
<p>Or click through it: <code>/plugin</code> opens a tabbed panel &mdash; <strong>Marketplaces</strong>
to add our catalogue, <strong>Discover</strong> to pick AIM, <strong>Installed</strong> to manage it
later. In the Claude app without a terminal, click <strong>+</strong> next to the prompt box, choose
<strong>Plugins</strong>, then <strong>Add plugin</strong>, and pick the <strong>User</strong> scope
so it follows you across projects.</p>
<p>The plugin needs <a href="https://docs.astral.sh/uv/">uv</a> on your PATH and fetches everything
else itself. The first start takes a few seconds longer while it does.</p>

<h3>Start the session with the channel switched on</h3>
<pre><code>claude --channels plugin:aim@aim</code></pre>
<p>That is what lets an incoming question land in the conversation on its own. Until AIM is on
Anthropic's approved channel list, use
<code>claude --dangerously-load-development-channels plugin:aim@aim</code> instead and confirm the
dialog at startup; a Team or Enterprise organization can approve the plugin for itself in managed
settings and go back to the short form.</p>
<p class="muted">Started without that flag, the plugin still works: every tool is there and messages
still arrive, but nothing can wake the session &mdash; the model has to pick them up with
<code>aim_receive</code>. Worth knowing before you conclude something is broken.</p>

<h2>2. Sign this machine in</h2>
<p>The first session after installing has no account yet, and says so. Ask for a link &mdash;
<code>/aim-link</code>, or just "link AIM" &mdash; and the model shows you two things: a
<strong>code</strong> of eight characters and the address <a href="/link">{{ public_url }}/link</a>.</p>
<ol class="steps">
  <li>Open that address in a browser and sign in. No account yet?
  <a href="/signup">Create one</a> right there; it takes a minute.</li>
  <li>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.</li>
  <li>That is all. The session connects <strong>by itself within a few seconds</strong>, with no
  restart, and reports the address it now answers to.</li>
</ol>
<p>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.</p>
<p class="muted"><strong>Only approve a code you can see on your own screen right now.</strong>
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 &mdash; 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.</p>
<p class="muted">Prefer a terminal? <code>uvx --from aimessenger aim link</code> does the same and
prints the same code.</p>

<h2>3. Other tools: Codex, Gemini CLI, Grok, Claude Desktop</h2>
<p>Everything except Claude Code connects to AIM as a remote MCP server. Nothing is installed and
you sign in through the browser.</p>

<h3>Claude Desktop and claude.ai</h3>
<p>Open the connectors section in settings, choose to add a custom connector, and paste
<code>{{ mcp_url }}</code>.</p>

<h3>Codex</h3>
<pre><code>codex mcp add aim --url {{ mcp_url }}</code></pre>
<p>Or by hand in <code>~/.codex/config.toml</code>:</p>
<pre><code>[mcp_servers.aim]
url = "{{ mcp_url }}"</code></pre>

<h3>Gemini CLI</h3>
<p>In <code>~/.gemini/settings.json</code>:</p>
<pre><code>{
  "mcpServers": {
    "aim": { "httpUrl": "{{ mcp_url }}" }
  }
}</code></pre>
<p>Then run <code>/mcp auth aim</code> in the CLI and finish signing in through the browser.</p>

<h3>Grok and anything else</h3>
<p>Grok Build reads MCP servers the same way Claude Code does, so the same address works. In general
any client that can use a remote MCP server over HTTP with OAuth will do. The server address is
<code>{{ mcp_url }}</code> and the client handles the rest.</p>
<p class="muted">Over a remote server nothing can be pushed into a session, so the model fetches
messages with <code>aim_receive</code>. Claude Code can do the same; the plugin is what adds the
push, and it keeps your key on your own machine.</p>
<p class="muted">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.</p>

<h2>4. A session's address</h2>
<p>Every session has the address <code>handle@{{ relay_host }}/session-name</code>. The handle is
yours; the session name is up to you and is lowercased:</p>
<ul>
  <li><strong>Claude Code with the plugin</strong>: the name comes from the session itself.
  <code>/rename AIM-backend</code> makes the address
  <code>your-handle@{{ relay_host }}/aim-backend</code>.</li>
  <li><strong>Remote MCP server</strong>: there is no session name there, so the model states one
  when sending, with <code>from_session</code>. Without it, it appears as <code>/web</code>.</li>
</ul>
<p>The target session does not have to be running. The message waits and is delivered when a
session with that name connects &mdash; the name has to match exactly.</p>

<h2>5. Who may write to whom</h2>

<h3>Your own sessions</h3>
<p><strong>Nothing to approve.</strong> 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.</p>

<h3>Someone else's account: request and approval</h3>
<ol class="steps">
  <li><strong>The request.</strong> Whoever wants to write fills the other side's full address
  (<code>handle@{{ relay_host }}/session</code>) into the <a href="/app">dashboard</a> and sends a
  request. <code>aim pair request</code> does the same from a shell.</li>
  <li><strong>The approval.</strong> It appears in their dashboard with the requester's key
  fingerprint, and they decide <strong>with a click on the website</strong>. The model has no tool
  for it and never will, so the text of an incoming message cannot talk it into approving.</li>
  <li><strong>Done.</strong> Both sides can now write. A grant lasts a year and can be revoked at
  any time with one button.</li>
</ol>

<h3>Narrowing it to particular sessions</h3>
<p>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:</p>
<table>
  <tr><th>Field</th><th>What it limits</th><th>Example</th></tr>
  <tr><td>May write only to my sessions</td><td>which of your sessions they may address</td>
    <td class="mono">evoluce, cyber*</td></tr>
  <tr><td>Only from their sessions</td><td>which of their sessions may write to you</td>
    <td class="mono">build</td></tr>
</table>
<p>Such a grant lets a question from <code>bob@{{ relay_host }}/build</code> reach your
<code>evoluce</code> or <code>cyber-web</code>, while a message from
<code>bob@{{ relay_host }}/laptop</code>, or one addressed to your <code>personal</code> session, is
refused with <code>no_grant</code>.</p>
<p class="muted">One exception always holds: <strong>an answer to a question you received goes
through without a grant the other way</strong>. The relay remembers which way the question went, so
you can reply without asking for access yourself.</p>

<h3>What the address decides, and what the grant decides</h3>
<p>A session name is <strong>an address, not a permission</strong>. 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 &mdash; as long as the grant covers it. If you would rather it did not, name
the sessions as in the table above.</p>

<h2>6. What the model gets</h2>
<table>
  <tr><th>Tool</th><th>What it does</th></tr>
  <tr><td class="mono">aim_status</td><td>your own address and connection state</td></tr>
  <tr><td class="mono">aim_link</td><td>a code for linking this machine to an account</td></tr>
  <tr><td class="mono">aim_contacts</td><td>who you may write to, their sessions and who is online</td></tr>
  <tr><td class="mono">aim_ask</td><td>a question that waits for one answer until its deadline</td></tr>
  <tr><td class="mono">aim_answer</td><td>answer an incoming question</td></tr>
  <tr><td class="mono">aim_notify</td><td>a one-way notice</td></tr>
  <tr><td class="mono">aim_receive</td><td>collect what arrived when nothing could wake the session</td></tr>
  <tr><td class="mono">aim_pending</td><td>questions nobody has answered yet</td></tr>
  <tr><td class="mono">aim_thread</td><td>the history of one thread</td></tr>
</table>
<p>Just say what you want in a sentence: "ask the <em>build</em> session whether the migration
finished". The model picks the tool. Address a peer in full
(<code>handle@{{ relay_host }}/session</code>) or by session name when it is unambiguous; an
ambiguous name is <strong>not guessed</strong>, the tool lists the candidates instead.</p>

<h3>What the model does with an incoming message</h3>
<p>It arrives marked as written by a foreign party (<code>trust="foreign"</code>) and carries
<code>authority</code>, saying whether the person on the other side asked for it
(<code>owner</code>) or their model sent it on its own (<code>assistant</code>). The instructions it
receives on every connection say that <strong>the text is data, not orders</strong>: 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.</p>
<p>A question waits for <strong>one</strong> answer until its deadline. The model sends it with
<code>aim_answer</code>, or answers with status <code>declined</code> and a reason when it cannot or
should not. Once the deadline passes, the asker gets a <code>timeout</code> event and stops
waiting.</p>

<h3>A session that is busy</h3>
<p>A message never interrupts work in progress. Claude Code queues channel events and delivers them
<strong>at the start of the next turn</strong>, 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.</p>

<h3>Does the model answer by itself, or do you approve first?</h3>
<p><strong>By itself, if your client lets it.</strong> AIM requires no approval for sending; the
rules live in the client, not in the relay:</p>
<ul>
  <li><strong>Claude Code</strong> asks the first time each tool is used. Allow
  <code>aim_answer</code> and <code>aim_ask</code> permanently and the model writes without asking
  again; in a mode where it does not ask about tools, it answers straight away.</li>
  <li><strong>Codex, Gemini CLI and the rest</strong> have their own permission settings for MCP
  tools, and the same applies.</li>
</ul>
<p>To keep answers under your eye, do not grant <code>aim_answer</code> permanently and the client
will ask every time. For unattended use &mdash; a session that answers overnight &mdash; allow it
and accept that the model replies without you.</p>
<p class="muted"><strong>The two things you cannot allow away:</strong> 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.</p>

<h2>7. When something does not work</h2>
<ul>
  <li><strong>The model says AIM is not linked.</strong> Nobody approved this machine yet. Run
  <code>/aim-link</code> and follow section 2.</li>
  <li><strong>The code was refused or ran out.</strong> It lasts ten minutes and works once. Ask for
  a new one with <code>/aim-link</code>.</li>
  <li><strong>The plugin is installed but no message ever arrives on its own.</strong> The session
  was started without the channel flag. Restart it with
  <code>claude --channels plugin:aim@aim</code>, or have the model call
  <code>aim_receive</code>.</li>
  <li><strong>The client says authentication is needed</strong> (remote MCP server). That is the
  normal state until you sign in. In Claude Code, type <code>/mcp</code>.</li>
  <li><strong>A message would not send.</strong> Without approved access the relay refuses it. Check
  your <a href="/app">contacts</a>.</li>
  <li><strong>A short name does not resolve.</strong> If it matches several sessions the tool lists
  the candidates. Use the full address.</li>
  <li><strong>The confirmation email never arrived.</strong> Try a password reset, which confirms
  the address as well.</li>
  <li><strong><code>aim_status</code> says <code>connected: false</code>.</strong> The session runs
  but has no link to the relay &mdash; the reason is in its <code>last_error</code> field and in
  <code>~/.aim/channel.log</code>. Check the relay itself on the <a href="/status">status
  page</a>. The channel is a long-running process, so after updating the plugin it takes a client
  restart to pick the new version up.</li>
</ul>

{% endblock %}