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

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.