---
name: pair-with-brain
description: Walk the owner through connecting their brain to another person's Alexandria brain (relay pairing / key exchange), hands-off — you run every step; the owner only relays a short code and confirms three words. Use when they say "connect me with <person>'s brain", "pair with <person>", "let <person>'s agent send me things", "add a peer", "set up federation with <person>", "someone gave me a pairing code", "connect peer <code>" / "connect this code", or paste/hand you a five-word code (five lowercase hyphenated words IS a pairing code — treat it as a request to join). NOT for sending to an already-paired peer (that's vault-federation).
served: true
---

# Pair with another brain

Pairing is the one-time key exchange that lets two Alexandria brains push items to each
other. **You drive the whole thing** — the owner never types a command. They do exactly two
human things: **relay a five-word code** to the other person over a channel they trust, and
**compare three verification words** out loud. Your job is to make those two moments clear and
run everything else.

Two things never change: content leaves a brain only on the owner's fire (pairing itself sends
nothing but a hello), and **the three verification words are the security check — you never
confirm a pairing the owner hasn't personally OK'd.**

## First, know your two levers

**Which surface are you on?** Use whichever tool set you actually have:
- **In a chat client (served brain):** the MCP tools `peer_pair_invite`, `peer_pair_check`,
  `peer_pair_join`, `peer_pair_confirm`, `peer_pair_abort`, `peer_pairings`.
- **In a vault checkout (Claude Code):** the CLI — `alexandria peer invite|check|add|confirm|
  abort|pending`. Run it with the shipped binary (`.alexandria/app/.venv/bin/alexandria`).

They mirror each other exactly; the steps below name both.

**Which role is the owner?**
- They want to reach out first, OR they're the one who'll send the code → **Invite** (below).
- Someone already gave them a five-word code → **Join**.

The relay is already configured (every brain ships pointed at the shared relay), so there is
nothing to "point at" — don't ask about relays or URLs.

## Invite (the owner goes first)

1. **Ask what to call the peer** — a name (e.g. "Jane's brain") and optionally a short handle.
2. **Start it.** `peer_pair_invite {name, handle?}`  ·  CLI: `alexandria peer invite "<name>"
   --handle <h>`. You get back a **five-word code**.
3. **Hand the owner the code with clear instructions:** *"Send this code to <person> over
   something you trust — a call or Signal, not email. It expires in 10 minutes: `word-word-
   word-word-word`. Tell them to open their brain and say they have a pairing code."*
4. **Wait for them, without blocking.** When the owner says the peer has entered it (or
   otherwise **no more than once a minute**) run `peer_pair_check {handle}` · CLI
   `alexandria peer check <h>`. While it says `waiting`, tell the owner you're still waiting
   and check again in a minute — don't spin: the relay meters rendezvous reads (30 per
   10 minutes from one network, and every check costs one), so checking every few seconds
   only delays seeing the answer.
5. When it returns **`ready`** with three words, go to **The word check** below.

## Join (the owner was given a code)

A pasted five-word code (or "connect peer <code>") IS a request to join — go straight here.

1. **Take the code** the owner was given.
2. **Ask what to call this peer** (optional) — a name/handle for how they'll appear in *this*
   vault. If the owner doesn't care, skip it; the peer's own self-chosen name is the default.
3. **Redeem it.** `peer_pair_join {code, name?, handle?}` · CLI: `alexandria peer add <code>
   [--handle <h>] [--name "<name>"]`. It returns three words (and the effective handle). Go to
   **The word check** — the confirm/abort in the next step use that handle.
   - If it errors that the code expired or is wrong: the code lasts 10 minutes and is
     single-use — ask the other person to send a fresh one (they re-invite).

## The word check — the one moment that matters

Both brains now show the **same three words**. Present them plainly, **say what confirming grants
the peer** (the `grant` field on the ready result — todos/notes/knowledge by default; calendar
events are excluded), and ask the owner to compare with the other person, out loud, over the
channel they trust:

> "You should both see these three words: **anchor · ledger · quartz**. Read them to each
> other. Do they match exactly on both sides? (Confirming lets Jane send you todos, notes, and
> knowledge — not calendar events; you can narrow that later.)"

- **Owner says they match →** finalize: `peer_pair_confirm {handle}` · CLI `alexandria peer
  confirm <h>`. Tell them they're connected and can now share items both ways. A new peer's
  first few items are held for review — surface them with `federation_review` (`list`, then
  `approve <id>` / `reject <id>`) · CLI `alexandria federation review …`, never by editing the
  note.
- **Owner says they DON'T match (or isn't sure) →** do **not** confirm. Run `peer_pair_abort
  {handle}` · CLI `alexandria peer abort <h>`, and explain plainly: a mismatch can mean someone
  is intercepting, so the pairing is cancelled and the token revoked — **don't retry with the
  same code**; start a fresh invite if they want to try again. (If the abort reports the revoke
  wasn't confirmed, tell them to retry the abort when the connection is back.)

**Never call confirm on the owner's behalf, and never treat "looks close" as a match.** The
whole security of federation rests on this being a real human check.

## Resuming, and after

- **Lost track?** `peer_pairings` · CLI `alexandria peer pending` lists every pairing in
  progress and its next step (waiting for an answer, or words ready to check).
- **Once paired:** the owner can push to the peer and vice-versa — that's the `vault-federation`
  skill. Pairing also links the peer to a matching `People/` note (so provenance stamps become
  working links); if the owner keeps no note for them, that's fine, provenance stays plain text.
- **Re-checking identity later:** the three words aren't a standing secret and aren't shown on
  `peer list` — to re-verify a peer out of band any time, `alexandria peer verify <handle>` prints
  them on demand.
- **Undo a pairing:** `alexandria peer remove <handle>` (the block button — it revokes the peer's
  access at the relay).
