# hoptell

> hoptell is an open-source MCP server for developer tools. Self-hosted relay that lets Claude Code, Codex and other coding agents message each other. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Linux
- **Repository:** https://github.com/eminuzun/hoptell
- **MCP Registry name:** io.github.EminUZUN/hoptell
- **Categories:** developer tools, communication
- **Listing updated:** 2026-11-15

## About

hoptell moves plain text between agent sessions through one small relay you run on your LAN or VPN. Agents can sit on different machines and use different Claude or OpenAI accounts; messages travel only through your relay, and each agent still talks to its own AI provider as usual.

The key feature is waking idle agents. Claude Code can be woken by a hook or channel notice, agents run inside tmux get a fixed notice typed into their prompt, and other clients poll. Notices never contain the message text. Agents announce roles such as reviewer or backend, so a message can go to one name, to everyone with a role through @reviewer, or to @all. A Claude Code plugin can start reviewer agents and collect verdicts, and an optional Telegram owner channel lets agents ask you questions.

The relay is a single Node process needing Node.js 22 or newer, with a Docker image available. The README warns that it relays text agents may act on, so read its security section before connecting agents with relaxed permissions. On Windows only the relay and polling tools work.

## Features

- **Peer messaging:** Lists peers and sends messages to a name, a role or everyone.
- **Idle-agent wake-up:** Uses hooks, channels or tmux notices to wake sleeping sessions.
- **Roles and swarms:** Agents announce roles so a team can be addressed by function.
- **Reviewer agents:** A Claude Code plugin starts reviewers and gathers their verdicts.
- **Telegram owner channel:** Lets agents ask you questions and request approval from your phone.
- **Self-hosted relay:** Runs as one Node process or Docker image with no accounts.

## Good for

- Hand a code review from Claude Code to a Codex session
- Run an implementer and a reviewer in separate worktrees
- Let a CI box agent report to a lead agent
- Approve landing a change from your phone
- Broadcast a task to all agents with a role

## Install

### Claude Code (Terminal)

```sh
claude mcp add hoptell --env HOPTELL_TOKEN='<HOPTELL_TOKEN>' -- npx -y hoptell
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "hoptell": {
      "command": "npx",
      "args": [
        "-y",
        "hoptell"
      ],
      "env": {
        "HOPTELL_TOKEN": "<HOPTELL_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "hoptell": {
      "command": "npx",
      "args": [
        "-y",
        "hoptell"
      ],
      "env": {
        "HOPTELL_TOKEN": "<HOPTELL_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "hoptell": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "hoptell"
      ],
      "env": {
        "HOPTELL_TOKEN": "<HOPTELL_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "hoptell": {
      "command": "npx",
      "args": [
        "-y",
        "hoptell"
      ],
      "env": {
        "HOPTELL_TOKEN": "<HOPTELL_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "hoptell": {
      "command": "npx",
      "args": [
        "-y",
        "hoptell"
      ],
      "env": {
        "HOPTELL_TOKEN": "<HOPTELL_TOKEN>"
      }
    }
  }
}
```

## Tools

- `list_peers`: Lists connected agent peers.
- `send_message`: Sends a message to a peer, role or everyone.
- `wait_for_message`: Waits for an incoming message.
- `read_inbox`: Reads queued messages.
- `ack_messages`: Acknowledges messages.
- `check_snapshot`: Checks files in the session's folder.
- `read_diff`: Reads the commits of the session's repository.

## FAQ

### Does it need accounts or a cloud service?

No. It is self-hosted and agents may use different Claude or OpenAI accounts.

### Which agents are supported?

Claude Code, Codex and Antigravity, plus any MCP-capable client using polling.

### What does it require?

Node.js 22 or newer, and tmux 3.2 or newer to wake terminal agents like Codex.

### Does it work on Windows?

Only the relay and polling tools work on Windows; macOS and Linux are supported.

### Is hoptell free?

Yes. hoptell is open source, so you can use and self-host it for free.

### How do I add hoptell to Claude Code?

Run this command in your terminal: claude mcp add hoptell --env HOPTELL_TOKEN='<HOPTELL_TOKEN>' -- npx -y hoptell

### What are the best alternatives to hoptell?

The closest alternatives to hoptell are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/hoptell
