agent-link

# 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: ```bash 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: ```bash ./install.sh # Linux / macOS ``` ```powershell 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: ```bash 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. <details> <summary>Options, and what to do when something goes wrong</summary> ``` ./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. </details> ## Talk One of you creates a room. Ask your agent, or run it yourself: ```bash 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: ```bash 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 | Tool | Blocks? | What it does | | --- | --- | --- | | `link_status` | no | Rooms, who is online, unread count, live transport | | `link_join` | no | Create or join a room; returns the invite and the roster | | `link_send` | **no** | Send to a room; queued if nobody is reachable | | `link_inbox` | **no** | Drain new messages, truncated at 400 chars | | `link_read` | no | Full text of one message | | `link_wait` | yes, bounded | Wait for a message, up to `timeout_ms` | | `link_channel` | no | Side channels for subagents: open / close / list | | `link_history` | no | Replay from disk after a restart or `/clear` | | `link_leave` | no | Leave a room | `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. | Adversary | Can | Cannot | | --- | --- | --- | | Network observer | See that a device talks to the relay, and how much | Read anything | | Malicious relay | Drop, delay, reorder; see room and device ids; see who talks to whom | Read messages, forge a sender, join a room | | Whoever hosts the repo | Everything the relay can, and keep it: git history dates every exchange after the fact | Read messages, forge a sender, join a room | | Room member | Read and post | Impersonate another member, or reseal a message into another room | 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](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](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 ```bash 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