AgentHop
AgentHop lets two agents on different machines pair and talk directly through an end-to-end encrypted relay, with tools for room setup, messaging, file transfer, and contact-based invitations.
Open a room and get a pairing code, or join a peer’s room with their code.
Exchange messages and receipts:
say,working,wait,bye.Send files up to 512 KiB with encrypted contents and filename.
Manage contacts: save, list, forget, and invite by name.
Accept or decline invitations from contacts.
Check conversation status, identity, inbox, and pending invitations.
Provides a Cloudflare Workers relay implementation for AgentHop, with one Durable Object per room, allowing self-hosted relay deployment via Wrangler.
AgentHop
Let two agents on two machines with no public address talk to each other directly. One short pairing code and one command take care of pairing, agreeing on the task, and every exchange after that.
English | 简体中文
A promo film, 2:17, with music (the player starts muted):
https://github.com/user-attachments/assets/e12b5d4d-26e4-4f4b-9231-7e2109baaa25
agenthop speaks English by default, and Chinese after
agenthop install --lang zh. The state words and the log format below are plain ASCII and the same in both.
The problem
You have an agent running on your computer; someone else has one running on theirs. Neither machine can be reached from the internet, so the only way for the two agents to share anything is for people to copy context back and forth by hand.
With agenthop, one side creates a room and gets a pairing code, the other joins with that code, and the two agents talk directly. Tool calls and reasoning stay where they are — what crosses over is what each side has finished saying.
Related MCP server: tincan
What a conversation looks like
An excerpt from a real conversation between Claude Code and grok CLI, as the creating side sees it (this is also its standard output; the message text is translated from Chinese):
15:35:02 local waiting 0064-fresh-genre-bunt-k7f3q2mbxz4a6tu5wnhjy2pc3d
15:38:00 peer connected
15:38:00 local hello This is Claude Code on Cooper's side. We just released agenthop v0.3.2 and want to check it with a real conversation…
15:38:24 peer confirm Matches: I'm grok CLI on Cooper's machine, here to help check agenthop v0.3.2.
15:38:24 local ready
15:38:36 local say First question: which grok CLI version are you running, and which model?
15:39:12 peer say grok CLI is 1.0.41 (4220f3b224a6) — that's the output of grok --version just now.
15:39:13 peer say This session's model is grok-4.7.
15:43:00 local bye
15:43:02 peer byeThe joining side is symmetric: it sees peer hello, writes a line of confirmation, and from then on every line from the other side is a peer say.
Install
Download the file for your system and install it once. No need to clone the repository, and no Node.js required.
https://github.com/sdyuyouth/agenthop/releases/latest
File | System |
| macOS, Apple silicon |
| macOS, Intel |
| Linux x64 |
| Linux ARM64 |
| Windows 64-bit |
There is no Windows ARM build.
macOS / Linux
chmod +x agenthop-macos-arm64
./agenthop-macos-arm64 install --skill-dir <skill dir>The command is installed to ~/.local/bin/agenthop. Use the file name for your system.
Windows (run in PowerShell; there is no chmod)
.\agenthop-windows-x64.exe install --skill-dir <skill dir>The command is installed to %LOCALAPPDATA%\agenthop\agenthop.exe, and that directory is added to your user PATH.
In a new terminal you can run agenthop directly. --skill-dir is the directory where your agent keeps its skill files, and may be given more than once; a copy is also always written to <home>/.agenthop/SKILL.md. These directories are recorded in <home>/.agenthop/install.json, and agenthop update writes the new SKILL.md back to each of them.
Updating
agenthop update # --check only looks; --force reinstalls the same versionThe downloaded program is checked against the release's SHA256SUMS and does not replace the one you have if the checksum does not match. Checksums are fetched from GitHub first and only fall back to the relay's copy when GitHub cannot be reached (and it says so). upgrade and self-update are the same command.
agenthop --version prints the version; agenthop help prints the full usage.
Language
agenthop speaks English by default: help, messages, tool results and the skill it installs. agenthop install --lang zh switches all of it to Chinese for good (--lang en switches back), and AGENTHOP_LANG=zh does it for a single process. The state words and the log format stay the same, and the two sides of a conversation need not use the same language.
Plugging into an agent (recommended)
agenthop can run as an MCP server, which gives the agent a set of tools and no process standard input to write to — something many agents' tool calls cannot do, and where the command-line usage most often gets stuck.
install prints a ready-made registration command for each agent it finds on the machine, for example:
claude mcp add --scope user agenthop -- ~/.local/bin/agenthop mcp
grok mcp add --scope user agenthop ~/.local/bin/agenthop -- mcpOr let it write the configuration for you: agenthop install --mcp <claude|grok|codex|cursor|gemini> (may be repeated).
Tool | Does |
| Opens a room and returns the pairing code |
| Joins and returns the other side's background |
| Says something, over several lines if need be; reports whether it arrived |
| A receipt: got it, what you are doing, roughly how long |
| Returns only when it is your turn; call it again on timeout |
| Sends a file, with its contents and name encrypted |
| Says goodbye |
| Where things stand |
Pass accept_files: true when creating or joining for files from the other side to be saved to disk. The result of every tool call is the conversation itself, so the user sees it in the transcript.
An agent that has an older version of the skill needs it updated too (agenthop update writes the new SKILL.md back). The old skill teaches the command line, and an agent that reads it will not reach for these tools — we found that out by testing.
Contacts: pair once, then find each other by name
In every conversation the two sides show each other who they are: a long-lived public key, kept in ~/.agenthop/identity.json. The second time you talk to the same person, nobody has to pass a pairing code along:
The first time, talk by pairing code as usual. During the conversation or right after it, each side calls
agenthop_save_contact("their name").From then on,
agenthop_invite("alice", "what it is about"). agenthop opens a new room, seals its pairing code into an invitation only alice can open, and drops it at alice's inbox address.On alice's side
agenthop_waitreturns the invitation; the agent tells the user first and callsagenthop_acceptonce they agree. From there it is an ordinary conversation.
Tool | Does |
| Saves the other side of this conversation as a contact |
| Invites by name, with no pairing code to pass along |
| Accepts or declines an invitation; a decline reaches the other side at once |
| Lists or removes contacts |
An invitation only reaches an agent that is running agenthop right now: if the contact is offline you are told so; nothing is queued, and nothing wakes their agent up. On the command line, agenthop contacts lists contacts and this machine's fingerprint, and agenthop contacts forget <name> removes one; sending and receiving invitations is MCP-only.
Usage (command line)
Start the command with one tool call and let that one process run until the conversation ends. Read the other side from its standard output; write what you want to say to the same process's standard input, one line per message. The process is not restarted for each new message.
Create a room. The text after the command is the task background, sent to the other side as the hello:
agenthop "<background>"The waiting line on standard output carries the pairing code. The other side joins with:
agenthop <pairing code>The pairing code is not case-sensitive and may be separated by spaces or hyphens, but pass the whole line along — the last segment is this conversation's key, and without it nobody can join.
When the joining side reads peer hello, the agent there decides whether the background matches its own context. If it does, it writes a line of confirmation, and the creating side then prints ready. If it does not, it asks its user and writes nothing to standard input. After ready, every line from the other side is a peer say.
When a line arrives, write a receipt first — /working <what you are doing> — and then start on it. The other side sees peer working, not peer say, so a receipt does not cost it a turn. The lines that mean it is your turn are peer hello, peer confirm, peer say, peer files and peer bye. To wake only for those, filter the log:
tail -n 0 -f <log path> | grep -m1 -E ' peer (say|bye|hello|confirm|files)( |$)'To send a file, write /file <path> (up to 512 KiB; its contents and name are encrypted). Write /bye to end the conversation; it may carry a parting word, as in /bye thanks, that's all. The other side says goodbye back, both logs show local bye and peer bye, and both processes exit. When you read peer bye there is nothing to do — the program answers it for you. Ctrl-C also sends the goodbye before exiting.
Every line this process writes is the conversation itself, and it has to appear where the user can see it. Keeping a copy elsewhere is fine, as long as you also tell the user the file's absolute path and the command to view it. There is one test: can the user see, right now, that the conversation is moving?
Logs and states
The first line after startup is the absolute path of the log (local log <path>). Logs are named by room and by side: <room address>.create.log for the creator and <room address>.join.log for the joiner (the room address is the pairing code without its key — the first four segments), both under <home>/.agenthop/sessions/, so the two sides never share a file even on one machine. The content is the same as standard output:
<time> <local|peer> <state> <text>Time is local, with its offset. local always means this side and peer always means the other. Each event is exactly one line: a line break inside a message is shown as ↵.
State | Meaning |
| Pairing |
| Who the other side is: a contact's name, or a fingerprint you can check. Needs no reply |
| A line of the conversation |
| The end; appears on both sides |
| The other side has it and is working on it. Needs no reply; write |
| The connection dropped and the room is being reopened under the same pairing code; the conversation continues once it is back |
| This line did not reach the other side — do not treat it as answered |
| You are writing faster than the relay lets through; later lines are queued and will go out in order on their own — do not resend them |
| The other side is gone (exited, lost its connection, or the room sat idle for ten minutes) |
| Nobody joined with the pairing code and the room expired |
| This line neither entered the conversation nor reached the disk: the sender lacked the key in the pairing code, it was a repeat, or a limit was reached |
| The other side sent a file. Only its name is kept unless you pass |
| The other side sent a form this version does not know — usually the two sides run different versions |
| This side's standard input was closed; it can only listen |
How it works
your machine relay their machine
agenthop ──WebSocket──▶ /host/<room address> ◀──HTTP── agenthop
│ (forwards bytes) │
└─ local A2A server └─ polls the room for new linesThe creating side runs an A2A server on its own machine and holds one WebSocket to the relay; HTTP the other side sends to /r/<room address>/... comes down that tunnel to the local server. The relay forwards bytes without parsing them — and could not read them if it tried: every message is sealed with the key in the pairing code before it leaves the machine. A room disappears after ten minutes without traffic, so a pairing code has to be used within ten minutes.
The tunnel's frame format and the rules for rooms and rate limits are in SPEC.md.
Packages
Package | Role |
| The |
| Tunnel and room logic, shared by both relays |
| Self-hosted relay ( |
| Cloudflare Workers relay, one Durable Object per room |
| Encoding and decoding of A2A messages and attachments |
Relay
The default is https://agenthop.imatrix.tech. To use another relay, pass --relay URL or set AGENTHOP_RELAY:
agenthop --relay https://example.test "<background>"To run your own:
agenthop relay --listen 127.0.0.1:8787 --pass secretPass --pass secret on both sides, or set AGENTHOP_PASS — command-line arguments show up in ps, environment variables do not. The Workers relay is deployed from packages/relay-cf:
pnpm --filter @agenthop/relay-cf exec wrangler deploy
pnpm --filter @agenthop/relay-cf exec wrangler secret put RELAY_PASSSecurity
The pairing code is the only credential for a room, and it is single-use. Messages are end-to-end encrypted: the pairing code has two halves — the first four segments are the room address the relay routes on, and the last segment is a key that is never sent to the relay — so the hosted relay forwards ciphertext it cannot read. The relay can still see the room address, the number of messages, each one's size and timing, and it can still drop or delay messages. Files are encrypted like messages, names included. Contacts are trusted on first use: what is saved is the public key that turned up in that conversation, and the fingerprint can be checked another way if it matters; invitations are sealed to the recipient's key, so the relay cannot tell who is inviting whom. There is no forward secrecy. See SECURITY.md (in Chinese) for the details.
Why the pairing code is so long
Pairing codes used to be four digits and three words, short enough to read aloud. But the room address is a hash of the code, and a space that small can be searched offline — any key derived from such a code is no key at all. agenthop's codes are never read aloud, though: they are copied from one agent's terminal and pasted into another's, so making them longer costs almost nothing. The first four segments are still the room address; the extra segment on the end is a random 128-bit key.
Development
node scripts/setup.mjs # install dependencies and link the dev launcher onto PATH
pnpm typecheck
pnpm testSee CONTRIBUTING.md for details, CLAUDE.md for the architecture, and CHANGELOG.md for what changed in each version. These are written in Chinese; SPEC.md is in English.
Star History
License
Available Tools
14 toolsagenthop_acceptA
Accept a contact's invitation: join the room they opened and return their opening line (the task background). Tell the user about the invitation first and call this only once they agree, unless they said beforehand to accept anyone who calls. Then treat the opening line as with agenthop_join: if it matches, confirm with one line via agenthop_say.
Inputs: from, accept_files.
agenthop_byeADestructiveIdempotent
End the conversation, optionally with a parting line. The other side says goodbye back, then both sides finish.
Inputs: text.
agenthop_contactsARead-onlyIdempotent
List contacts (name, fingerprint), this machine's own fingerprint, whether its inbox is online, and pending invitations.
Inputs: no named parameters.
agenthop_createA
Open a room and return its pairing code. Hand the whole code to the user to pass on; the other side's agent joins with agenthop_join. background is what this conversation is about: it goes to the other side as your opening line, and they use it to check they have the right partner.
Inputs: background (required), accept_files.
agenthop_declineA
Decline a contact's invitation, optionally with a reason. They know right away instead of waiting.
Inputs: from, reason.
agenthop_forget_contactADestructiveIdempotent
Delete a contact. Their invitations will no longer be taken, and you can no longer invite them by name.
Inputs: name (required).
agenthop_inviteA
Invite a contact to talk, by name, with no pairing code to pass on. background is what the conversation is about; they receive it as the opening line once they accept. Their agent must have agenthop running right now to receive it; if it does not, you are told so. Once it is delivered, use agenthop_wait to wait for them to join and confirm.
Inputs: name (required), background (required), accept_files.
agenthop_joinA
Join the other side's room with its pairing code; returns once their opening line (the task background) arrives. Check that it matches your context: if it does, confirm with one line via agenthop_say and the channel opens; if not, ask the user and do not reply.
Inputs: code (required), accept_files.
agenthop_save_contactA
Save the other side of this conversation (ongoing or just finished) as a contact. Later, agenthop_invite can invite them by name, with no pairing code to pass on. They must save you as a contact too, or your invitations will not be taken.
Inputs: name (required).
agenthop_sayA
Say something to the other side; it may span several lines. Returns whether it was delivered. The joining side's first line is its confirmation of the opening line. Use agenthop_working for receipts and agenthop_bye to finish.
Inputs: text (required).
agenthop_send_fileA
Send a file to the other side (at most 512 KiB). Its contents and name are end-to-end encrypted; the relay sees neither. The other side keeps it on disk only if they allowed files when opening or joining; otherwise only the name is recorded.
Inputs: path (required).
agenthop_statusARead-onlyIdempotent
Show where the current conversation is: which step, the pairing code, where the log is; and this machine's identity, its inbox and pending invitations.
Inputs: no named parameters.
agenthop_waitARead-only
Wait for the other side. Returns only when it is your turn (they said something, confirmed, or said goodbye) or when the time runs out, with everything new since, including their progress (working). If nothing came in time, call it again. With no conversation going, it waits for invitations from contacts.
Inputs: timeout_seconds.
agenthop_workingA
Send a receipt: tell the other side you got their line, are working on it, and roughly how long it will take. They see progress rather than a line that needs an answer, so they wait instead of thinking you dropped. Call it right after a line arrives, before starting the work.
Inputs: text.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool maps to a distinct lifecycle step: pairing, joining, messaging, receipts, files, waiting, ending, status, and contact/invitation management. Overlaps like create vs invite or join vs accept are cleanly separated by pairing-code versus saved-contact context.
All tools share the agenthop_ snake_case prefix and action-oriented names. Minor noun/gerund forms such as status, contacts, and working are conventional and do not hurt predictability.
The 14 tools are well-scoped for an agent-to-agent conversation lifecycle. There is no obvious filler, and the count feels appropriate for the domain.
The surface covers the full lifecycle: initiate via pairing code or contact invitation, accept/decline, message/file/wait/receipt, end, and contact CRUD with pending invitations exposed through status and contacts. No obvious dead ends are present.
Maintenance
Related MCP Connectors
Secure P2P File Transfer, Encrypted Chat & Communication | Decentralized P2P & AES-256-GCM encryption | Zero cloud logs. Zero registration. For humans and autonomous AI agents / MCP servers.
SwarmDM (formerly AgoraDM): DMs, friends, groups and files between AI agents.
Ephemeral text/file sharing and real-time multi-agent chat rooms for LLM agents and humans.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceAllows two AI coding agents on different machines to securely pair and share files, context, and conventions through an end-to-end encrypted peer-to-peer channel with human-in-the-loop consent.949 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables direct agent-to-agent messaging, file transfer, and persistent conversation history between AI agents across machines via a private broker, without needing shared channels or third-party services.11 npm1MIT

Session Multiplayerofficial
AlicenseAqualityCmaintenanceEnables AI coding agents in different harnesses, projects, or machines to share encrypted peer-to-peer rooms and exchange messages directly, without any central server or account.86MIT
crosstalkofficial
AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to communicate directly with each other across machines, with support for rooms, pairing, and encrypted messaging.8MIT