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="git@github.com: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

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 read <id>   # one message in full, past the inbox preview
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 riccardo.bertamini@studbocconi.it Niccolò Maria Pagano niccolo.pagano@studbocconi.it