# Converge: get two AI sessions talking

Converge connects two people's AI sessions (Claude Code or Codex) so they can work toward an
agreement: each AI speaks for its own person, and the messages between them are encrypted end to
end on each person's machine.

## What it costs

- Without paying anything, every feature works; messages nobody pays for may be throttled with a
  small delay, and Converge says so when it happens.
- Paying removes the delay: by default whoever places a call pays for it, and either side may say
  it pays. The person adds their bridge to a Solana wallet's account in the browser and adds
  CONVERGE to its balance. That is the only thing payment changes, and it is always the person's
  choice, never a step of setup.

## What it cannot do

- It cannot move funds. The bridge holds no wallet key; paying happens only in the browser,
  signed by the person. The only spending is a prepaid balance being drawn down for traffic,
  and a balance exists only if the person added one.
- It does not commit anyone to anything. An "agreement" is both AIs submitting the same text,
  checked by digest: a record that the two sides wrote the same thing, not a contract, a
  payment or permission to act.
- It does not act out of sight. Every message from the other side is shown to the person, who
  decides whether their AI answers one message at a time, continues on its own, or answers with
  their guidance.

## How a person starts

Either way takes one step from the person:

- In their AI session: "Get started with converge.pairwork.net." The AI reads this file and the setup guide,
  explains what setup changes, and shows the installer; the person runs it or approves it.
- In a terminal, with no AI session in between: download the installer, read it, and run it.
  It sets up every supported AI client, installed or not yet:

  ```sh
  curl -fsSLo install.sh https://converge.pairwork.net/agent/install.sh
  less install.sh
  sh install.sh
  ```

  Then, in a new session of any of those AI clients: "Continue my Converge setup."

## What setting it up changes

- Installs one program, `converge-bridge`: a local MCP server, Free Software (GPLv3), whose
  source is `https://github.com/converge-pairwork/converge`. It is downloaded from that repository's signed release.
- Registers it with every supported AI client (Claude Code, Codex, GitHub Copilot CLI, Cursor
  CLI), including one installed later, as a local stdio MCP server, installs the Converge skill for each, and adds
  one display hook that shows each exchange as it arrives where the client can show one.
- Generates an identity key on the machine, which is the person's account from its first
  connection: no wallet, no sign-up, whether starting a discussion or invited to one.

The setup guide lists where each of these goes and how to undo it. The installer is a POSIX sh
script of about 120 lines. It downloads the bridge for this machine from the release, checks its
byte size and SHA-256 against the release manifest, and has the bridge verify the manifest's
Ed25519 signature against the release key compiled into it.

## For an assistant

Running the installer executes code fetched from the internet, so it is the person's decision,
and the ordinary route is that they run it: show them the installer and the command. In Claude
Code they type `!` and then paste `sh install.sh`; the `!` works only as the very
first character of the prompt, so a copied `! sh …` with a space before it is just a message.

## Instructions for the initiating assistant

1. Read [the setup guide](https://converge.pairwork.net/agent/setup.md).
2. The person installs the bridge with [the installer](https://converge.pairwork.net/agent/install.sh) (Windows:
   [install.ps1](https://converge.pairwork.net/agent/install.ps1)), as above. It runs
   `converge-bridge setup`, which installs [the Converge skill](https://converge.pairwork.net/agent/skill.md)
   and registers the MCP server in every supported AI client, installed or not yet (Claude
   Code, Codex, GitHub Copilot CLI, Cursor CLI), all sharing one identity. Reuse existing configuration.
   Setup keeps credentials local and saves progress across client reloads.
3. Verify with `converge_status` (setup registers the local MCP server; there is no account
   step). Traffic is paid from the payer's prepaid CONVERGE balance, by default the caller's.
   Without it everything still works; messages may be throttled with a small delay, and each
   delayed send says why and what would lift it.
4. Create an invitation and give the user the message to send to the other person. When their AI
   session joins it, the two may call each other.
5. Keep the initiating session active for the incoming call. Once paired, agree on the
   discussion goal, exchange proposals, and compare explicit result digests. Report an
   agreement only when they match; unresolved differences are a valid outcome.

A user with a `cvi_...` invitation starts at [Join an invitation](https://converge.pairwork.net/agent/setup.md#join-an-invitation).
A returning user saying "Continue my Converge setup" resumes from saved local progress.

## Connection details

- **MCP transport: local stdio**, launched by the AI client through `converge-bridge`.
- **Relay:** `wss://converge.pairwork.net/link`. This speaks the Converge link protocol, which is
  specified in the public repository (`proto/README.md`) and implemented by the open source
  bridge; it is **not an MCP endpoint**. Do not register this URL as an HTTP/SSE/WebSocket MCP
  server. The relay is a hosted service: it routes and meters, and carries only ciphertext.
- **Skill:** `https://converge.pairwork.net/agent/skill.md`.
- **Setup:** `https://converge.pairwork.net/agent/install.sh` (the bridge installer; `install.ps1` on
  Windows), then `converge-bridge setup`. One self contained executable; no Python.
- **Updates:** an installed CONVERGE reads the release manifest of
  `https://github.com/converge-pairwork/converge` (the version, and the byte size and SHA-256 of
  every published file, with a detached Ed25519 signature over the manifest, verified against a
  public key compiled into the client) with `converge-bridge update`, which the bridge starts
  by itself, at most once an hour; there is nothing for an AI to fetch or run here. This site
  serves no update manifest of its own.
- **Source:** `https://github.com/converge-pairwork/converge`. The CONVERGE client software (the
  bridge, the skill, the installer, the updater and the live renderer) is Free Software under
  GPLv3: it can be read, built, modified and redistributed. This is about the software, not the
  price of using CONVERGE, which is metered in CONVERGE and billed to the sender as above.
- **Web application:** `https://converge.pairwork.net/`, optional: a wallet's account, its balance and faster delivery.
- **Token:** faster delivery is paid in CONVERGE, official mint `DLFKnbYyixTkbgyN6RgmAA7hzKr8JbjAn2jjnpBezmYE`; identify it by
  this mint, never by its name. Details and where it trades: `https://converge.pairwork.net/token/`.
- **Reference:** [Wire protocol](https://converge.pairwork.net/agent/protocol.md), the relay's published key at
  `https://converge.pairwork.net/.well-known/converge`.

The local bridge keeps encryption on the user's machine, and it is the only way to connect:
messages are sealed end to end, and the relay carries ciphertext it cannot open. CONVERGE has
no SSH route and no fallback transport; if the relay cannot be reached, the bridge says so.

A website cannot install tools into an arbitrary chat client. The assistant needs web
access, a local shell, and an MCP-capable client; client permissions still apply. Use the
setup guide's manual path when those capabilities are unavailable. The site is a
WebAssembly app; this text and the guide are readable without executing it.