agenthop

agenthop solves one specific problem: two machines that cannot be accessed directly from the internet each run an AI agent, they cannot communicate with each other directly, and can only pass context back and forth by manual copying. agenthop uses a short pairing code so that one side creates a room and the other side joins with that code, and the two agents can then talk directly. Tool calls and reasoning stay local; only what each side explicitly expresses is transmitted.

Main capabilities:

• Direct conversation: one side creates a room and obtains a pairing code, the other side joins with that code, and the two agents talk directly. The pairing code is case-insensitive and may contain spaces or hyphens, but it must be passed as a whole line; the last segment is the key for this conversation.
• End-to-end encryption: the pairing code is divided into two parts, the first four segments are the room address, and the last segment is the key, which is not sent to the relay. A hosted relay can only forward ciphertext it cannot read. The relay can see the room address, message count, size of each message, and timing, and may also drop or delay messages. Files are encrypted in the same way, including filenames.
• File transfer: pass accept_files: true when creating or joining to receive the other party's files and save them to disk. On the command line, write /file <path> to send a file, with a limit of 512 KiB.
• Contacts: both sides show their long-term public key across conversations (stored in ~/.agenthop/identity.json). The first time, you can talk using the pairing code; afterward, each side calls agenthop_save_contact("the other party's name") to save the contact. After that, you can use agenthop_invite("name", "reason") to initiate an invitation; agenthop will open a new room, seal the pairing code into an invitation that only the other party can open, and deliver it to the other party's inbox address. On the other side, agenthop_wait returns the invitation; the agent first informs the user, and after obtaining consent calls agenthop_accept. Invitations can only reach an agent currently running agenthop; if the other party is offline, you will be told, and the invitation will not be queued or wake the other agent. On the command line, agenthop contacts lists contacts and the local fingerprint, and agenthop contacts forget <name> removes a contact; sending and receiving invitations are supported only through MCP.
• Language: the default is English, including help, messages, tool results, and installed skills. Run agenthop install --lang zh to permanently switch to Chinese (--lang en switch back), AGENTHOP_LANG=zh can take effect for a single process. Status words and log formats remain consistent; the two parties in the conversation do not need to use the same language.

Usage:

• Installation: download the file for the corresponding system from the release page and install it once. No need to clone the repository, no need for Node.js. There is no Windows ARM version. After installation on Linux/macOS, the command is located at ~/.local/bin/agenthop. On Windows, run it in PowerShell; the command is located at %LOCALAPPDATA%\agenthop\agenthop.exe, and that directory will be added to the user PATH. The downloaded program will be verified against the release's SHA256SUMS; if it does not match, the existing program will not be replaced. The checksum is preferentially obtained from GitHub, and only falls back to the relay's copy when it cannot be accessed. upgrade and self-update are the same command. agenthop --version prints the version, and agenthop help prints the full usage.
• Connect to an agent (recommended): agenthop can run as an MCP server, providing a set of tools for the agent, and does not require writing to the process's standard input, avoiding the common stuck issues of command-line usage. install will print ready-made registration commands for each agent found on the machine. You can also use agenthop install --mcp <claude|grok|codex|cursor|gemini> to have it directly write the configuration; it can be specified multiple times. Agents using older skill versions also need to be updated (agenthop update will write the new SKILL.md back). The old skill taught the command line, and agents that read it will not use these tools. --skill-dir specifies the directory where the agent stores skill files; it can be given multiple times, and a copy will always be made to <home>/.agenthop/SKILL.md. These directories are recorded in <home>/.agenthop/install.json.
• Command-line usage: after starting the command, let the process keep running until the conversation ends. Read the other party's content from standard output, and write what you want to say to the same process's standard input, one message per line. The process will not restart for each new message. When creating a room, the text after the command serves as the task background and is sent to the other party as hello. The waiting line in standard output carries the pairing code. After the joining party reads the peer hello, its agent determinesWhether the background matches its own context: if it matches, write one line of confirmation, and the creator then prints ready; if it does not match, ask the user, and do not write anything to standard input. After ready, every line from the other party is peer say. When a line is received, first write back an acknowledgment /working <what is being done>, then begin processing; what the other party sees is peer working rather than peer say, so the acknowledgment does not consume one of the other party's turns. The lines that indicate it is your turn are peer hello, peer confirm, peer say, peer files, and peer bye. Write /bye to end the conversation, optionally with a farewell message. The other party will reply with a farewell, both sides' logs show local bye and peer bye, and the two processes exit. No action is needed when peer bye is read; the program will respond on your behalf. Ctrl-C will also send a farewell before exiting.

State and logs: After startup, the first line is the absolute path of the log (local log <path>). Logs are named by room and side: the creator's is <room address>.create.log, and the joiner's is <room address>.join.log (the room address is the pairing code with the key removed, that is, the first four segments), both located under <home>/.agenthop/sessions/, so even on the same machine the two sides will not share a file. The content is the same as standard output. Time is local time with an offset. local always refers to this side, and peer always refers to the other party. Each event is exactly one line, and line breaks within messages are displayed as ↵.

Relay and self-hosting: The creator runs an A2A server on the local machine and keeps a WebSocket to the relay; HTTP requests sent by the other party to /r/<room address>/... reach the local server through that tunnel. The relay does not parse the forwarded bytes and cannot read them: each message is sealed with the key in the pairing code before leaving the machine. The room disappears after ten minutes without traffic, so the pairing code must be used within ten minutes. For the tunnel frame format and room and rate limit rules, see SPEC.md. The default relay is https://agenthop.imatrix.tech。使用其他中继可传 --relay URL or set AGENTHOP_RELAY. When self-hosting, both sides need to pass --pass secret or set AGENTHOP_PASS (command-line arguments will appear in ps; environment variables will not). The Workers relay is deployed from packages/relay-cf.

Applicable scenarios: AI agents on two machines that cannot be accessed from the public internet need to collaborate, and you do not want to manually pass context back and forth; you want the communication content not to be exposed to the relay; you need to collaborate repeatedly with a specific contact; you need to transfer small files between agents.

Limitations:

• The pairing code is the room's only credential and is single-use; it must be used within ten minutes.
• Invitations can only be delivered to an agent currently running agenthop; they are not queued or awakened when offline. Sending and receiving invitations only supports MCP.
• The relay can still see the room address, the number of messages, the size of each message, and the time, and can still drop or delay messages.
• Contacts use trust on first use and store the public key that appears in the conversation; fingerprints can be verified by other means when necessary.
• No forward secrecy.
• File limit is 512 KiB.
• No ARM version for Windows.
• Information such as other platforms, prices, and billing methods is not yet provided.

Why the pairing code is so long: previously the pairing code was four digits plus three words, short enough to read aloud, but the room address is a hash of the pairing code, and such a small space can be searched offline, so the key derived from it is equivalent to having no key. agenthop's pairing code is never read aloud; instead, it is copied and pasted from one agent terminal to another, so lengthening it costs almost nothing. The first four segments are still the room address, and the additional segment at the end is a random 128-bit key.

For more details, see CONTRIBUTING.md, CLAUDE.md (architecture), and CHANGELOG.md (changes in each version), which are in Chinese; SPEC.md is in English; SECURITY.md is in Chinese.