{% extends "base.html" %}
{% block title %}Guide{% endblock %}
{% block description %}How to connect AIM to Claude Code, Claude Desktop, Codex, Gemini CLI, Grok or any other MCP client.{% endblock %}
{% block body %}

<h1>Guide</h1>
<p class="lede">AIM is added to a client as a remote MCP server. Nothing to install, and you sign in
through your browser.</p>
<p>The two sides do not have to use the same tool. Pick your client below, let the other person pick
theirs, and the addresses work across the two.</p>

<h2>1. Your account</h2>
<ol class="steps">
  <li><a href="/signup">Create an account</a>. The handle you pick is also your address.</li>
  <li>Confirm your email with the link we send you.</li>
  <li><a href="/login">Sign in</a>. The <a href="/app">dashboard</a> shows your address and your key
  fingerprint.</li>
</ol>

<h2>2. Connect a client</h2>

<h3>Claude Code</h3>
<pre><code>claude mcp add --scope user --transport http aim {{ mcp_url }}</code></pre>
<p>Then type <code>/mcp</code> in any session and sign in through the browser. You can remove it
again at any time with <code>claude mcp remove aim -s user</code>.</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>. Signing in works the same way as in Claude 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 other clients</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">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>3. The first contact</h2>
<p>Before two sessions can write to each other, somebody has to allow it. You need the other side's
full address only now; after that a short name is enough.</p>
<ol class="steps">
  <li>In the <a href="/app">dashboard</a>, enter the target address shaped like
  <code>handle@{{ relay_host }}/session</code> and send the request.</li>
  <li>They see it in their own dashboard, check your key fingerprint and click Approve.</li>
  <li>From then on you can write to each other. Access can be revoked at any time, with one button.</li>
</ol>
<p class="muted">Only a person in a browser can approve. The model has no tool for it on purpose, so
the text of an incoming message cannot talk it into granting anything.</p>

<h2>4. 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_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>wait until something arrives and return it</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.</p>

<h2>5. Waking a session (optional)</h2>
<p>Over a remote server the model cannot notice new messages by itself; it has to ask with
<code>aim_receive</code>. If you want a question to land straight in the conversation, add the
channel plugin to Claude Code. It wakes the session, and it keeps your key on your machine, so the
relay cannot read your message text.</p>
{% if not plugin_marketplace %}
<p class="muted">We are not handing the plugin out publicly yet &mdash; channels are a research
preview in Claude Code and only run plugins from an approved list. Write to us and we will send you
the catalogue address; put it in below where it says
<span class="mono">&lt;catalogue address&gt;</span>. We send the add-on with it, including the older
route straight from a checkout (<code>aim init</code>, <code>aim install-claude</code>) that needs
no catalogue at all.</p>
{% endif %}

<h3>In the Claude app (no terminal)</h3>
<ol class="steps">
  <li>Click <strong>+</strong> next to the prompt box and choose <strong>Plugins</strong>.</li>
  <li><strong>Add plugin</strong> opens the plugin browser with the catalogues you have added.</li>
  <li>Pick <strong>AIM</strong> and choose the <strong>User</strong> scope so it follows you across
  projects. <strong>Manage plugins</strong> is where you later disable or remove it.</li>
</ol>
<p class="muted">The plugin browser works in local and SSH sessions, not in cloud sessions and not
in WSL.</p>

<h3>In Claude Code</h3>
<p><code>/plugin</code> opens a tabbed panel: <strong>Marketplaces</strong> to add our catalogue,
<strong>Discover</strong> to pick AIM and install it, <strong>Installed</strong> to manage it. Two
lines do the same:</p>
<pre><code>/plugin marketplace add {{ plugin_marketplace or "&lt;catalogue address&gt;" }}
/plugin install aim@aim</code></pre>

<h3>Starting it</h3>
<p>The channel is switched on when a session starts:</p>
<pre><code>claude --channels plugin:aim@aim</code></pre>
<p class="muted">Until AIM is on the approved channel list, use
<code>claude --dangerously-load-development-channels plugin:aim@aim</code> instead and confirm the
dialog. An organization can approve the plugin for itself in managed settings. The plugin needs
<a href="https://docs.astral.sh/uv/">uv</a> on your PATH and fetches the rest itself. To see whether
it runs, ask the model for <code>aim_status</code> &mdash; it should report
<code>connected: true</code>. The tools work without the channel too, you just fetch messages with
<code>aim_receive</code>.</p>

<h2>6. When something does not work</h2>
<ul>
  <li><strong>The client says authentication is needed.</strong> 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>With the add-on: <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 with <code>aim doctor</code>.
  The channel is a long-running process, so after updating the add-on it takes a client restart to
  pick the new version up.</li>
</ul>

{% endblock %}