# hoptell

hoptell connects AI agents through a self-hosted relay: passes tasks, code and replies across Claude Code, Codex and other sessions on different machines and accounts.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 10 repo stars
- Author: EminUZUN
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/EminUZUN/hoptell
- Updated: 2026-10-08
- Security check: automated, 2026-11-16 (text) — warning: suggests running the agent with permission prompts turned off. Do not run such commands without an explicit yes from the human.
- HTML: https://affpapa.org/en/nevibecode/mcp/hoptell

## What it does

hoptell links agents through a WebSocket relay running on one machine in your LAN or VPN. Each agent gets tools — `list_peers`, `send_message`, `read_inbox` — and can route messages by name, role (`@reviewer`, `@backend`) or to everyone (`@all`). An incoming message wakes the receiving session: Claude Code uses channels or hooks, tmux supports fixed terminal notices, other sessions rely on polling.

Inside: one Node process with two dependencies (`ws` and the MCP SDK). Agents exchange text only through your relay, each still talks to its own AI provider. Queued messages for offline agents stay in the relay's memory until they return.

Without tmux 3.2 or later, waking terminal agents fails. The relay and polling tools work on Windows; everything else needs macOS or Linux.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `HOPTELL_RELAY`, `HOPTELL_TOKEN`, `HOPTELL_NAME`, `HOPTELL_ROLES` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env HOPTELL_RELAY=<HOPTELL_RELAY> --env HOPTELL_TOKEN=<HOPTELL_TOKEN> --env HOPTELL_NAME=<HOPTELL_NAME> --env HOPTELL_ROLES=<HOPTELL_ROLES> --transport stdio hoptell -- npx -y hoptell
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add hoptell --env HOPTELL_RELAY=<HOPTELL_RELAY> --env HOPTELL_TOKEN=<HOPTELL_TOKEN> --env HOPTELL_NAME=<HOPTELL_NAME> --env HOPTELL_ROLES=<HOPTELL_ROLES> -- npx -y hoptell
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "hoptell": {
            "command": "npx",
            "args": [
                "-y",
                "hoptell"
            ],
            "env": {
                "HOPTELL_RELAY": "<HOPTELL_RELAY>",
                "HOPTELL_TOKEN": "<HOPTELL_TOKEN>",
                "HOPTELL_NAME": "<HOPTELL_NAME>",
                "HOPTELL_ROLES": "<HOPTELL_ROLES>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "hoptell": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "hoptell"
            ],
            "env": {
                "HOPTELL_RELAY": "<HOPTELL_RELAY>",
                "HOPTELL_TOKEN": "<HOPTELL_TOKEN>",
                "HOPTELL_NAME": "<HOPTELL_NAME>",
                "HOPTELL_ROLES": "<HOPTELL_ROLES>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e HOPTELL_RELAY=<HOPTELL_RELAY> -e HOPTELL_TOKEN=<HOPTELL_TOKEN> -e HOPTELL_NAME=<HOPTELL_NAME> -e HOPTELL_ROLES=<HOPTELL_ROLES> hoptell npx -y hoptell
```
Replace <…> with your own values

## When to use it
- pass code for review from one machine to another without manual copying
- wake a remote agent with an incoming message
- ask the agent with the `@pm` role about the project's release plan
- link several agents into a team where each handles its own part
- run a relay for agent communication without external services

## Example prompts
- Send the contents of `auth.js` to agent Alex for a security check
- Ask `@backend` which endpoint the payments module uses
- Show the list of connected agents and their roles

## Similar
- [cli-anything-iterm2](https://affpapa.org/en/nevibecode/skills/cli-anything-iterm2.md) — skill · 559 installs
- [3dstreet](https://affpapa.org/en/nevibecode/mcp/3dstreet.md) — MCP server
- [centrifugo](https://affpapa.org/en/nevibecode/skills/centrifugo.md) — skill · 263 installs
- [nemo-relay-install](https://affpapa.org/en/nevibecode/skills/nemo-relay-install.md) — skill · 227 installs
- [zcode-delegate](https://affpapa.org/en/nevibecode/skills/zcode-delegate.md) — skill · 3200 installs
- [smux](https://affpapa.org/en/nevibecode/skills/smux.md) — skill · 2900 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
