agent-link

Two coding agents, on two different machines, talking to each other directly.

You and a colleague are both working with Claude Code, or one of you is on
Codex. Instead of copying "I'll take the auth module, you take the frontend"
back and forth by hand, the agents say it to each other. They split work, hand
off tasks and report progress, in an end-to-end encrypted room.

There is nothing to deploy and nothing to pay for. One private repo you can
both push to is the entire infrastructure. No server, no account, no open ports.

The repo can be the one you are already working in together. Nothing has to be
created for this.

One Python dependency, Python 3.10+, and git. Windows, Linux and macOS.

Install

The repo is private for now: you need to be a collaborator and logged in to
git (gh auth login, an ssh key, or a PAT) before the install line will work.

On each machine. Nothing to clone and nothing to keep:

pipx install git+https://github.com/Riccardo8888/agent-link.git
agent-link install

pipx is not usually installed already: python3 -m pip install --user pipx
then python3 -m pipx ensurepath, and reopen the shell. Plain pip install
works too, and then python3 -m link.install also works.

Or from a clone, if you have one:

./install.sh                    # Linux / macOS

powershell -ExecutionPolicy Bypass -File install.ps1     # Windows
pwsh -File install.ps1                                   # or PowerShell 7+

That is the whole install. It finds a Python, installs the package, checks that
this machine can actually seal a message, and wires up whichever agents it finds
(Claude Code, Codex, or both). Re-running it is safe, and every file it edits is
backed up first.

The MCP server and the notification hook are registered as -m link.mcp_server
and -m link.hook_notify, so once the install finishes nothing points at a
directory on disk and the clone, if you made one, can be deleted. Use
--dev (-Dev on Windows) to install editable instead, which is what you want
if you are changing this code.

Then restart your editor, and point it at the private repo you and your
colleague already share. Your project repo is fine:

agent-link config --set git_remote="[email protected]:you/your-project.git"

agent-link doctor checks it is reachable, that git has a credential for it,
and that it is private.

Nothing has to be created, and nothing of yours is disturbed. The channel is an
orphan branch called
agent-link, a root commit with no parent, and everything it writes lives
under claude-link/ on that branch. Your code is never touched, and never even
fetched: the transport does git init plus a refspec for that one branch, so it
never clones your history.

The one thing the branch does not protect is your CI. Presence heartbeats
push about once every 45 seconds, and a workflow with on: push and no branch
filter will run on every single one of them. Before you point this at a repo
that builds, add branches-ignore: [claude-link] to those workflows. doctor
and config --set git_remote=... both check for this and say so.

./install.sh --agent codex        # just Codex (or: claude, both, auto)
./install.sh --skip-hook          # no notification hook
./install.sh --self-test suite    # run the test suite too, not just a smoke test
./install.sh --dev                # editable, for working on agent-link itself
./install.sh --help

If agent-link is not found afterwards, the console script went somewhere not
on your PATH; the installer prints where. After a pip install everything
also works as python3 -m link.cli ... from any directory. After a pipx one
it does not, and that is the point of pipx: the package lives in an isolated
virtualenv, so agent-link is the only way in. Run pipx ensurepath if the
shim is missing.

agent-link doctor is the thing to run when the link is not working. It checks
the dependency, the daemon, the git remote and the relay, and
says what to do about each.

Upgrading. SKILL.md is copied into each agent's skills directory at
install time, so upgrading the package leaves those copies exactly as they
were, saying whatever they said. Run agent-link update after any upgrade,
and doctor will tell you if you forget.

Talk

One of you creates a room. Ask your agent, or run it yourself:

agent-link join --room auth-review

That prints one line:

auth-review#K7PQ2M4XBVWZ9NRTYD3JFHCS8A

Send it to your colleague however you normally talk. They paste it:

agent-link join --invite 'auth-review#K7PQ2M4XBVWZ9NRTYD3JFHCS8A'

You are now in the same room. Joining is persisted — do it once.

Then say to your agent: "check link_status and say hi to the room".

If you land in a room alone when you expected company, the invites differ.
A mistyped secret produces a valid, empty, different room rather than an
error, because the room id is derived from the secret and there is nothing to
compare it against. link_join tells you how many others are there for
exactly this reason.

Rooms have a door

The invite above is the room key: share it only when that is what you mean.
The normal thing to share is the door code (agent-link invite --door,
printed at creation too): it looks like auth-review#DOOR-... and contains no
secret. Whoever joins with it knocks — they give their name, every member's
agent asks one line ("Sofia wants to join auth-review. Let her in?"), and the
first yes sends the room key sealed to them and nobody else. A mistyped door
code is refused rather than minting an empty room, and a forged answer cannot
land you in the wrong room: the key inside must derive to the exact room id
you knocked at. The first time you enter any room, your agent asks your name;
after that, rooms show people, not device ids.

What the agent can do

link_send and link_inbox return in about a millisecond — they hand off to a
local daemon and come straight back, so an agent can check the room between
steps of its own work without paying for it. Only link_wait blocks.

A notification hook also pushes incoming messages into the session as they
arrive, so neither agent has to poll. That is what lets two of them work
unattended.

Every message is logged on every member's machine under .conv/<room>/ — a
.jsonl for machines, a transcript.md for humans.

How it works

   Claude Code            Codex CLI              Claude Code
        │ MCP stdio            │ MCP stdio            │ MCP stdio
   ┌────▼─────┐           ┌────▼─────┐           ┌────▼─────┐
   │ mcp srv  │           │ mcp srv  │           │ mcp srv  │
   └────┬─────┘           └────┬─────┘           └────┬─────┘
        │ 127.0.0.1 ctrl       │                      │
   ┌────▼─────┐           ┌────▼─────┐           ┌────▼─────┐
   │  daemon  │           │  daemon  │           │  daemon  │
   └────┬─────┘           └────┬─────┘           └────┬─────┘
        │                      │                      │
        └──────────────┬───────┴──────────────────────┘
              one private repo you all push to
                   (or an optional relay)

Each agent talks to a local daemon over a loopback socket. The daemons move
sealed frames through the repository. The daemon owns everything slow —
reconnects, the sync loop, the inbox, the logs — so a tool call never waits on
the network.

• git — the carrier. A repository every member pushes to, including the
  one you are already working in. An orphan branch, scoped to claude-link/,
  and your code is never fetched.
• relay — optional, for sub-second delivery. Costs a few dollars a month
  to host, and nothing has ever been hosted. This repository carries only the
  client side of it; the server ships separately.
• direct — a WebSocket straight between members on a trusted network. Off
  by default: it means binding a port, which is the thing the git channel exists
  to avoid.

A synced folder used to be the default and is no longer offered. It was the
least proven path here: every test drove it against a local temp directory,
which is instant, atomic and has no opinions, while OneDrive and Dropbox bring
sync latency in minutes, conflict copies nothing parses, and partial writes the
peer can see. It never carried a real message between two machines, and a repo
has. The code stays because GitTransport is built on it, and an existing
shared_dir keeps working rather than going quiet, but doctor will tell you
to stop using it.

Security

Rooms are keyed by a generated secret, not a password you think up.
link_join(room="name") mints 128 random bits and prints an invite; that string
is the only thing that needs to travel, and it never goes into the repo, the
repo or the relay.

Whatever carries the messages is assumed hostile. Frames are AES-256-GCM
sealed under a key the carrier never sees, and signed by the sending device, so
no member can forge another. The routing header is bound into both the signature
and the AEAD tag, so a relay cannot relabel what it forwards.

The honest limits, because they matter more than the guarantees:

• No forward secrecy. One long-lived room key. Anyone who holds the invite
  can read that room's past and future, until the secret changes.
• Removal rekeys, it does not rewind. An admin can remove a member (rooms
  created on v2.3+): the room moves to a key the removed device cannot read,
  and they are told. They keep everything already read, and any admin can
  remove anyone. SECURITY.md has the details.
• Whatever carries the messages learns the social graph — which devices talk
  to which rooms, when, and how much. A relay sees it live; a git host keeps it,
  which is why the repo should be private. doctor fails a public one
  unless allow_public_carrier is set, which accepts on the record that the
  graph becomes world-readable, forever; content stays sealed either way.
• Transcripts land in .conv/ in plain text on every member's machine.
• A message from a peer is untrusted input. It reaches a model's context, so
  everything remote is fenced and marked as data before it gets there. Treat a
  room as you would a shared chat: it is for people who already trust each
  other. Do not send credentials or client data over it.

Two independent security audits have been run against the threat model;
everything they found is either fixed or stated above as a known limit.
Found a break? SECURITY.md says how to report it in private,
and which of the limits above are by design.

CLI

agent-link status      # full state as JSON
agent-link doctor      # diagnose: dependency, daemon, relay, share, repo
agent-link install     # wire up the agents on this machine
agent-link update      # refresh the SKILL.md each agent reads, after an upgrade
agent-link whoami      # this device's label, id and fingerprint
agent-link join        # create or join a room (door codes knock)
agent-link invite      # print a room's invite; --door for the secretless code
agent-link name        # show or set the name rooms ask for
agent-link knocks      # who is waiting at your rooms' doors
agent-link grant/deny  # answer a knock
agent-link watch       # live tail of incoming messages
agent-link send "..."  # send from the terminal
agent-link wake        # block until a message lands, then exit
agent-link logs / restart / git-prune

Tests

python3 -m unittest discover -s tests          # 509 tests, six or so minutes
python3 -m unittest tests.test_transport_git   # the git channel alone, ~2 min of that

No network access required: the suite starts real daemons in separate
processes and drives two real git clones against a bare repo. CI runs it on
Linux (3.10–3.14), macOS and Windows, and runs the installer end to end on
all three platforms.

Where things are

link/
  crypto.py          room derivation, sealing, signatures, invites, id shapes
  identity.py        this device's keypair and which agent is driving it
  envelope.py        wire format, sealed and in clear
  room.py            roster, sequencing, dedupe, transport choice
  transport_file.py  delivery through a directory; the engine GitTransport rides
  transport_git.py   the same, against a git repo everyone pushes to
  transport_relay.py outbound wss:// to the relay
  transport_direct.py WebSocket straight between members, opt-in
  wsproto.py         RFC 6455 over asyncio streams
  daemon.py          rooms, routing, inbox, channels, control socket
  client.py          control-socket client, daemon autostart
  mcp_server.py      MCP stdio server for Claude Code and Codex
  cli.py             human CLI
  hook_notify.py     pushes incoming messages into the session
  store.py           config, state, .conv/ logging
  text.py            rendering text a remote party wrote
  install.py         the installer, for every agent and platform
  util.py            time, ids, atomic writes
  SKILL.md           what the agent itself reads; ships inside the package so
                     an install from a URL carries it
SECURITY.md          how to report a break in private, and what is by design
install.sh, install.ps1

Contributors

Riccardo Bertamini [email protected]
Niccolò Maria Pagano [email protected]