gopalrajsuresh/covalent-bond

A secure channel that lets two AI coding agents on different machines work as one.
Quick start ·
How it works ·
Tools ·
Security ·
Architecture ·
Contributing
= 18">
---
A *covalent bond* is two atoms sharing a pair of electrons. Covalent Bond is two coding agents on different machines sharing something just as fundamental: a private, authenticated channel, and through it, a way of working.
Picture two developers pairing across a distance. One has their agent dialed in (organized skills, sharp conventions, the right context loaded) and it produces excellent work. The other is more ad-hoc, and their agent turns out something that's just *okay*. Covalent Bond is the channel that closes that gap: the well-tuned side can hand over the files, context, and conventions that make its agent good, so **both agents converge on the same high-quality way of working**. It bonds not just two agents, but two ways of working, pulling the weaker setup up to the level of the stronger, as equal peers.
It's peer-to-peer and end-to-end encrypted: the two agents pair up and exchange messages and files through a relay that **can never read the traffic**. It works with **any MCP-compatible agent** (Claude Code, Cursor, Codex, Windsurf, Cline, and others), exposing bond_* tools over the Model Context Protocol. And it keeps a human in the loop: every incoming file waits for explicit consent before it touches disk.
- 🤝 **Bonds two ways of working**: share files, context, and conventions so both agents level up together
- 🔒 **Authenticated E2EE**: a malicious relay can't read *or* MITM the channel
- 🌐 **Cross-machine**: pair agents anywhere, through a dumb relay (no inbound ports)
- 🙋 **Human-in-the-loop**: consent before any file is written; full audit log
- 🔌 **Agent-agnostic**: any MCP client, not tied to one vendor
> It doesn't magically clone one setup onto another. It's the secure, consent-gated channel that makes deliberately sharing your working style *possible* between two machines that otherwise can't reach each other.
Quick start
**Shortcut: let your agent set everything up.** Paste docs/AGENT-SETUP.md to any coding agent and say "set up Covalent Bond". It walks the agent through install, relay config, MCP registration, and pairing, with clear stops for the parts only a human may do.
Or do it yourself on **both machines** (steps 1–2), then pair (step 3).
1. **Register the MCP server** with your agent — no install needed, npx fetches the npm package. For Claude Code:
(--scope user makes the bond_* tools available in every project. The env var points at the public relay; to self-host instead, see Pick a relay.)
For other MCP clients (Cursor, Codex, Windsurf, …), this standard stdio-server config works in most of them; paste it into the client's MCP settings JSON (the top-level key is usually mcpServers or servers):
Windows and local-testing notes
On **Windows**, if your client struggles to spawn npx directly, wrap it: "command": "cmd", "args": ["/c", "npx", "-y", "covalent-bond"]. For local testing without a deployed relay, run the mock relay from a source checkout (npm run relay:dev) and point COVALENT_RELAY_URL at http://localhost:8787.
Prefer running from source?
The .env already contains the public relay URL. Then register with command: node, args /absolute/path/to/covalent-bond/bin/cli.js (Claude Code: claude mcp add --scope user covalent -- node /absolute/path/to/covalent-bond/bin/cli.js), no env var needed.
2. **Restart your agent session**, then verify: ask the agent to run bond_status. It should reply "No active session", which means the tools are live.
3. **Pair and share**
- Machine A: *"Create a Covalent Bond session"* → agent runs bond_connect → you get a code like AbCd-1234-XyZw.
- Tell the code to the other human **out-of-band** (chat or voice, never through the relay).