Metadata-Version: 2.5
Name: aimessenger
Version: 0.1.17
Summary: AIM - Cross AI Messenger: messages between AI coding sessions across tools, accounts and companies
Project-URL: Homepage, https://aim.mailows.com
Project-URL: Documentation, https://aim.mailows.com/docs
Project-URL: Plugin, https://github.com/mailows/aim-plugin
Author-email: DW Technology LLC <aim@mailows.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: agents,channel,claude-code,codex,mcp,messaging
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: aiosqlite>=0.21
Requires-Dist: argon2-cffi>=25.1.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: mcp>=2.2
Requires-Dist: platformdirs>=4
Requires-Dist: pydantic>=2.12
Requires-Dist: pynacl>=1.5
Requires-Dist: python-ulid>=3
Requires-Dist: typer>=0.15
Requires-Dist: websockets>=15
Provides-Extra: relay
Requires-Dist: starlette>=0.48; extra == 'relay'
Requires-Dist: uvicorn[standard]>=0.31; extra == 'relay'
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/) on PATH is all the plugin needs; it fetches the rest.

## Licence

BSD 3-Clause.
