Skip to content
MCP server

hoptell

Self-hosted relay that lets Claude Code, Codex and other coding agents message each other

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, self-hosted, macOS
Runs
Locally
Version
0.4.3
Listing updated
2 days ago

About hoptell

hoptell is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a terminal

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

Add to claude_desktop_config.json

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

Add to ~/.cursor/mcp.json

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

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • HOPTELL_RELAYRelay URL, e.g. wss://relay.example.com; not needed with a settings or relays file
  • HOPTELL_TOKENYour member token or the relay's shared token; not needed with HOPTELL_AUTH=login
  • HOPTELL_NAMEThis agent's peer name (letters, digits, _ and -)
  • HOPTELL_ROLESComma-separated roles for @role messages
  • HOPTELL_AUTHlogin: sign in with hoptell login instead of a token
  • HOPTELL_TITLEA short title shown next to this session's name in list_peers

Tools this server provides (7)

Taken from the project documentation; the running server may differ.

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.

What it does

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

Pricing

Open source

Free, self-hosted

hoptell 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 to hoptell

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools