palaver is now hoptell. This repository is archived and no longer maintained. Install the new package with npm install -g hoptell; the palaver-agents npm package is deprecated. To migrate, rename PALAVER_* environment variables to HOPTELL_* and move your settings file from ~/.config/palaver/.env to ~/.config/hoptell/.env. The default state directory is now ~/.hoptell (previously ~/.palaver).

palaver

Let AI coding agents talk to each other: across sessions, machines, accounts and tools.

palaver connects Claude Code, Codex, Antigravity (agy) and other MCP-capable agents through one small relay that you run yourself on your LAN or VPN. Agents get tools to list peers and send messages, and incoming messages wake idle agents up, so a Claude session on your laptop can hand a review to a Codex session on a colleague's workstation and get the answer back without anyone typing.

 laptop:   Claude Code ──┐                        ┌── Codex        :workstation
 laptop:   Codex       ──┼── palaver relay (LAN) ─┼── Claude Code  :workstation
 CI box:   Claude Code ──┘    one tiny process    └── ...

• Self-hosted, no accounts. One Node process. Agents can use different Claude or OpenAI accounts. Messages between agents travel only through your relay; each agent still talks to its own AI provider as usual.
• Wakes agents up. Claude Code gets messages pushed in as they arrive; Codex (or any terminal agent) gets them pasted in through tmux; anything else can poll.
• Teams and swarms. Agents announce roles (reviewer, backend, ...). Send to one agent by name, to every agent with a role (@reviewer), or to everyone (@all).
• Small and auditable. About 1,200 lines of JavaScript, two dependencies (ws and the MCP SDK).

palaver moves plain text between agents that may act on it. Read Security before connecting agents that run with relaxed permissions.

How it works

How an incoming message reaches the agent:

Push uses Claude Code's channels (research preview). Custom channels need the --dangerously-load-development-channels flag, and Claude Code asks you to confirm a "development channels" warning each time it starts with it. palaver detects the flag and adapts. Set PALAVER_PUSH=channel|listener to override the detection. Without the flag, the background listener starts after your first prompt in the session.

Quick start

Requirements: Node.js 20+, plus tmux 3.2+ to wake Codex/terminal agents. Supported on macOS and Linux; on Windows only the relay and polling tools work.

1. Install (every machine)

npm install -g palaver-agents    # puts `palaver` on your PATH

From source instead: git clone https://github.com/EminUZUN/palaver && cd palaver && npm install && npm link.

Claude Code users can install palaver as a plugin instead. It asks for the relay URL and token (stored in Claude Code's secure storage) and needs no separate MCP registration:

/plugin marketplace add EminUZUN/palaver
/plugin install palaver@palaver
claude --dangerously-load-development-channels plugin:palaver@palaver   # with push

The relay image is ghcr.io/eminuzun/palaver, and the server is listed in the MCP Registry as io.github.EminUZUN/palaver.

2. Start a relay (one machine)

mkdir -p ~/.config/palaver
cat > ~/.config/palaver/.env <<EOF
PALAVER_TOKEN=$(openssl rand -hex 32)
PALAVER_HOST=192.0.2.10
EOF
chmod 600 ~/.config/palaver/.env
palaver relay

Replace 192.0.2.10 with this machine's LAN or VPN address in the relay settings above. For Docker, use the same address and replace ... with your generated token: docker run -d -p 192.0.2.10:7777:7777 -e PALAVER_TOKEN=... ghcr.io/eminuzun/palaver. Publish the port on that address only. Without a host address, -p 7777:7777 publishes on all host addresses by default. See examples/. Health check: GET /healthz.

3. Configure each machine

~/.config/palaver/.env (chmod 600):

PALAVER_RELAY=ws://192.0.2.10:7777
PALAVER_TOKEN=<the same token>

Check: palaver list should connect and print the peers (none yet).

4. Connect your agents

Claude Code: register the MCP server once (user scope, all projects):

claude mcp add --scope user palaver -- palaver mcp

If an agent cannot find palaver (for example with nvm), use the full path that command -v palaver prints, here and in the configs below.

Then start Claude with push enabled:

PALAVER_NAME=laptop-claude claude --dangerously-load-development-channels server:palaver

Inside a clone of this repo, .mcp.json registers the server for you.

Codex: add to ~/.codex/config.toml:

[mcp_servers.palaver]
command = "palaver"
args = ["mcp"]
tool_timeout_sec = 1800                  # wait_for_message can block up to 1500s
default_tools_approval_mode = "approve"  # optional: no approval prompt per palaver tool call

Then start Codex through tmux so messages wake it:

palaver tmux laptop-codex -- codex

The launcher passes the peer name to Codex as a -c override, because interactive Codex starts MCP servers from a shared daemon that does not inherit your shell's environment. Detach with Ctrl-b d, reattach with tmux attach -t palaver-laptop-codex.

Antigravity (agy): register the MCP server once:

agy mcp add palaver palaver mcp
PALAVER_NAME=laptop-agy agy                      # listener mode, after your first prompt
palaver tmux laptop-agy --roles gemini -- agy    # or: woken through tmux

5. Try it

Ask either agent: "list palaver peers and say hi to laptop-codex".

For organizations

palaver has no central service: every organization runs its own relay, and agents connect from their users' machines.

1. Run a relay inside your network: the Docker image (examples/docker-compose.yml), or the systemd unit (examples/palaver-relay.service), behind your VPN or a TLS proxy.

2. Issue per-member tokens with a members file (see Teams and swarms), so people cannot use each other's agent names.

3. Roll out the client: the Claude Code plugin, or npm install -g palaver-agents plus the MCP config for Codex and Antigravity.

4. Allowlist the channel (Claude Code): with managed settings your users can start claude --channels plugin:palaver@palaver, without the development flag and its prompt:

   jsonCopy

   {
     "channelsEnabled": true,
     "allowedChannelPlugins": [{ "marketplace": "palaver", "plugin": "palaver" }]
   }
   

Teams and swarms

Names. Each agent has a peer name (PALAVER_NAME; default <hostname>-<pid>): letters, digits, _ and -. A new connection with a name already in use replaces the old one.

Roles. PALAVER_ROLES=reviewer,backend (or palaver tmux <name> --roles reviewer -- codex). list_peers shows them. Sending to @reviewer reaches every online peer with that role, and @all reaches every online peer. A busy peer gets it queued behind its unconfirmed messages. Fan-out is not queued for offline peers. A direct message to a name is queued while that peer is offline (up to 50 per peer, in relay memory). Roles are labels that agents choose for themselves to route work. They are not permissions.

Many people. Give each person their own token so nobody can impersonate anyone else's agents. Create a members file on the relay (chmod 600):

{ "members": [
    { "name": "alice", "token": "<openssl rand -hex 32>" },
    { "name": "bob",   "token": "sha256:<hex sha256 of bob's token>" } ] }

Run palaver relay --members members.json or set PALAVER_MEMBERS. A member may only use the name <member> or names starting with <member>- (alice-claude, alice-codex-2). The relay refuses member names that overlap, such as alice and alice-bob. You can combine a members file with a shared PALAVER_TOKEN; token holders can use any name. For separate teams, run separate relays. A relay is a single small process.

Example swarm on one machine:

palaver tmux alice-planner  --roles planner  -- claude
palaver tmux alice-codex-1  --roles backend  -- codex
palaver tmux alice-codex-2  --roles backend  -- codex
palaver tmux alice-reviewer --roles reviewer -- claude

Then tell the planner: "split the task, send backend work to @backend, and send the result to @reviewer".

Guard rails. Each connection may send at most 30 messages per 10 seconds, so two agents that keep replying to each other hit the limit instead of flooding everyone. Messages are plain text up to 100,000 characters.

CLI

palaver relay --host <ip> [--port 7777] [--members file.json]
palaver mcp
palaver tmux <name> [--roles a,b] -- <agent command...>
palaver list
palaver send <to> <message...>        # to: name, @role or @all; sends as $PALAVER_NAME without going online
palaver wait [seconds]                # goes online as $PALAVER_NAME and prints the next message
palaver listen <name> [seconds]       # waits on <name>'s local inbox (no relay connection)

Settings come from environment variables, otherwise from the first existing file of $PALAVER_ENV, ~/.config/palaver/.env, <package>/.env. See .env.example. In settings files, double-quoted values decode JSON-style escapes (\", \\, \n), single-quoted values are literal, and an empty value counts as unset.

Security

palaver's job is to put text from one agent in front of another agent. Plan for that:

• Anyone who holds a valid token can message your agents, and agents running with relaxed permissions (--dangerously-skip-permissions, auto-approve) may act on it. Keep tokens secret, use per-member tokens for groups, and run the relay on a private network or VPN only.
• Messages are labeled, not trusted. Agents are told that palaver messages come from other agents, not from their user. Message text cannot close the channel tag or forge a message boundary. That is guidance for the model, not a sandbox.
• Use TLS outside a trusted network. The relay speaks plain ws://. Put it behind a VPN (WireGuard, Tailscale) or a TLS proxy, for example Caddy: caddy reverse-proxy --from relay.example.com --to 127.0.0.1:7777, then use PALAVER_RELAY=wss://relay.example.com.
• tmux injection types into a live terminal. The injector pastes only into the pane where it started the agent, never into another pane, and holds back while it recognizes an approval prompt on screen. That is best effort, based on what the screen shows; prefer agents that ask before risky actions over auto-approve modes. A message that itself looks like a prompt is never typed: the agent gets a short notice to fetch it with read_inbox. Anything you have half-typed in that pane is submitted together with the message.
• Local inboxes live in ~/.palaver/inbox/<name>/ (0700/0600). Every message holds the sender name the relay verified.

To report a vulnerability, see SECURITY.md.

Limitations

• The relay keeps offline queues in memory; restarting the relay drops them.
• Delivery is at least once. "Delivered" means the receiving machine stored the message in the agent's inbox or pushed it into the session, not that the agent has acted on it. A message that was not confirmed is redelivered after the receiver reconnects, so in rare cases it arrives twice. A receiver gets at most 50 unconfirmed messages; more wait in its queue.
• Push depends on Claude Code channels (research preview); the flag name may change.
• No built-in TLS, persistence, message history or web UI, by design: the relay stays small.

Roadmap

Ideas that fit the small-relay design, roughly in order:

• palaver doctor: check settings source, relay reachability, identity, delivery mode, inbox and injector
• message expiry (TTL) and reply-to ids for request/response automation
• token revocation and reload without restarting the relay; optional per-member send rules
• optional on-disk queue so a relay restart keeps undelivered messages

Development

npm install
npm test        # starts its own relay on a random port; tmux tests run when tmux is installed

npm run test:e2e is an opt-in end-to-end test with real agents. It starts a relay and two Docker "machines" running Claude Code, Codex and Antigravity, then checks a roll call (@all) and a baton passed through every agent across both machines. It needs Docker and agent logins (--use-local-logins copies this machine's logins into the test containers for the run; CLAUDE_CODE_OAUTH_TOKEN / OPENAI_API_KEY also work; see test/e2e/run.mjs), uses your model subscriptions, and takes a few minutes. It runs only on your machine, never in CI.

See CONTRIBUTING.md. Licensed under the Apache License 2.0.