Covalent Bond

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:

   claude mcp add --scope user --env COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev covalent -- npx -y covalent-bond

(--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):

   {

"mcpServers": { "covalent": { "command": "npx", "args": ["-y", "covalent-bond"], "env": { "COVALENT_RELAY_URL": "https://covalent-bond-relay.gopalrajsuresh.workers.dev" } } } }

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?

   git clone https://github.com/gopalrajsuresh/covalent-bond.git covalent-bond

cd covalent-bond npm install npm test # optional but recommended; all suites run offline cp .env.example .env # PowerShell: Copy-Item .env.example .env

   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.

1. 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.
2. 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).
• Machine B: *"Join Covalent Bond session AbCd-1234-XyZw"* → agent runs bond_join.
• Either side: bond_status → Secure channel established → send files (bond_send) and messages (bond_message). Incoming files wait for the human to bond_accept.
• Done? bond_end on both sides.

How it works

Both agents meet at a relay that is untrusted by design — it forwards ciphertext it can never decrypt. The session code travels human-to-human, never through the relay, and that out-of-band secret is what authenticates the channel:

sequenceDiagram

participant A as Agent A (host) participant H as Humans (out-of-band) participant R as Relay (untrusted) participant B as Agent B (guest)

A->>A: bond_connect → session code A-->>H: code shared by chat / voice H-->>B: code entered on the other side B->>B: bond_join(code) A->>R: ephemeral public key (routing ID only) B->>R: ephemeral public key (routing ID only) Note over A,B: key = X25519 ⊕ session code → AES-256-GCM A->>R: ciphertext R->>B: ciphertext (relay sees nothing else) B->>B: file held until human runs bond_accept

If anything in the middle tampers with the key exchange, key confirmation fails and the session aborts before any data flows — a malicious relay can't read *or* impersonate either side.

Pick a relay

The relay is a dumb pipe and untrusted by design: it sees only a random routing ID and ciphertext, never the session code, keys, or plaintext, and a malicious relay still can't read or forge anything (that's covered by the test suite's MITM scenario). So either option below is equally secure; it's purely a convenience choice.

Option 1: use the public relay (fastest)

COVALENT_RELAY_URL=https://covalent-bond-relay.gopalrajsuresh.workers.dev

Sessions expire after 30 minutes of inactivity and nothing is retained. Best-effort availability, rate-limited.

Where to set COVALENT_RELAY_URL (either place works; a real environment variable wins over .env )

• `.env` file (simplest): copy .env.example to .env in the covalent-bond folder and edit the value. The MCP server reads it at startup, so it applies no matter which project you use the agent from.
• MCP client config: pass it when registering the server, e.g. for Claude Code:

  claude mcp add --scope user --env COVALENT_RELAY_URL=https://... covalent -- node /absolute/path/to/covalent-bond/bin/cli.js

For other MCP clients, add it to the server's env block in their JSON config.

After changing either, restart your agent session so the MCP server relaunches.

Option 2: deploy your own in ~2 minutes (free Cloudflare account)

npm install -g wrangler

wrangler login # opens the browser; create a free account if you don't have one cd cloudflare-worker wrangler deploy # prints your relay URL: https://covalent-bond-relay. .workers.dev

Then set COVALENT_RELAY_URL to that URL on both machines. Full details (Durable Object migration, optional per-IP throttle, local wrangler dev) are in cloudflare-worker/README.md.

Or let your agent do it

Paste this to any coding agent running in this repo:

Deploy my own Covalent Bond relay: install wrangler if missing, run wrangler login and wait for me to finish authenticating in the browser, then wrangler deploy from cloudflare-worker/, and tell me the URL to set as COVALENT_RELAY_URL on both machines. Follow cloudflare-worker/README.md.

The only manual step is the browser login; the agent handles the rest.

Pair two agents

1. Machine A: *"Create a Covalent Bond session."* → the agent calls bond_connect and returns a code like AbCd-1234-XyZw.
2. Share that code with Machine B out-of-band (chat, voice, in person). It's the secret that secures the link. Never paste it into the relay.
3. Machine B: *"Join Covalent Bond session AbCd-1234-XyZw."* → the agent calls bond_join.
4. When bond_status shows Secure channel established, start sharing: *"Send src/auth.js to my peer,"* or hand over the pieces that make your agent good: a skill file, a conventions doc, the context that shapes how it works. The peer sees a consent prompt and accepts before anything is written, and the received content arrives wrapped as untrusted data for the other agent to read and adopt.

Tools

• bond_connect — Create a session and get a shareable session code
• bond_join — Join a session using a code shared out-of-band
• bond_status — Connection status, pending transfers, and new events
• bond_send — Send a file to the connected peer, encrypted end to end
• bond_message — Send a short encrypted text message to the peer
• bond_wait — Long-poll for the next peer event
• bond_accept — Accept a pending file transfer after human consent
• bond_decline — Decline a pending file transfer
• bond_end — End the session and disconnect from the relay

Full reference:

| bond_accept | transferId | Write a pending file to ~/.covalent/incoming/ and return its content wrapped a