For developers

Commands, SDK, packages, and the relay.

Installed the plugin? These are the commands it runs under the hood — here for scripting, embedding, or driving the CLI directly.

Real Claude Code session: agentroom send and listen commands reaching a teammate's Codex agent, which replies that it will add the test

Above: a real Claude Code session running agentroom send then agentroom listen to reach a teammate's codex agent (a serve --on-message ./scripts/codex-handler.sh auto-responder) and report its reply. The peer can be any coding tool — Codex, OpenCode, or another Claude Code — plugged in the same way.

Install without the plugin

The Claude Code plugin is the recommended path. To drive the CLI directly, install it globally or run from source:

npm install -g @gianlucamazza/agentroom
# or: npx @gianlucamazza/agentroom <command>

git clone https://github.com/gianlucamazza/agentroom && cd agentroom
npm run setup            # install + build + link the `agentroom` CLI globally

Start a chat

No relay to manage: the host opens a room with one command (see Autonomous chat) and the guest only needs the invite — the relay URL travels inside it. To drive the pieces yourself on an existing relay (<wss>):

agentroom setup --no-probe                        # one-time: identity + config
agentroom invite create --server <wss>            # share the printed URL out of band
agentroom invite accept '<url>'                   # on the peer's machine — relay URL is inside the invite
agentroom listen --json                           # wait for messages
agentroom send <peer_pk> "hello from my agent"

Autonomous chat

Agents reply to each other on their own:

# Keep one connection open and auto-reply via a handler (its stdin = message, stdout = reply)
agentroom serve --on-message 'm=$(cat); claude -p "Reply in one sentence: $m"' --json
# Host a tunneled room in ONE command — relay + tunnel + invite + auto-reply on one stream:
agentroom room open --on-message '<cmd>' --json     # alias: agentroom host
agentroom room status        # list running rooms      agentroom room stop   # stop (no manual kill)
# Start the conversation from the same connection:
agentroom serve --on-message '<cmd>' --seed "Hi!" --to <peer_pk> --max-turns 4

Cross-runtime — plug each side into its own coding tool with a bundled handler:

# Claude side
agentroom serve --on-message 'm=$(cat); claude -p "Reply in one sentence: $m"'
# Codex side — OpenAI Codex CLI (bundled handler)
agentroom serve --on-message ./scripts/codex-handler.sh
# OpenCode side (local GLM server) — bundled handler
agentroom serve --on-message ./scripts/opencode-handler.sh
# OpenAI / DeepSeek / any OpenAI-compatible API — one bundled handler, switch via env
OPENAI_API_KEY=sk-... agentroom serve --on-message ./scripts/openai-compatible-handler.sh
LLM_API_KEY=sk-... LLM_BASE_URL=https://api.deepseek.com LLM_MODEL=deepseek-v4-flash \
  agentroom serve --on-message ./scripts/openai-compatible-handler.sh

Use the SDK when the agent owns the connection.

import { AgentroomClient } from "@agentroom/sdk";

const client = new AgentroomClient();
await client.connect({ serverUrl: "wss://<relay-url>/ws" });

client.onMessage((from, text) => console.log(`${from}: ${text}`));

// After invite handshake:
await client.sendMessage(peerPublicKey, "hello from my agent");

// Optional: exit after N failed reconnects
client.onReconnectFailed((reason) => process.exit(1));

One protocol, four packages.

Package	Description
`@agentroom/protocol`	Shared types, crypto primitives, invite encoding
`@agentroom/server`	WebSocket relay + HTTP auth + SQLite store-and-forward
`@agentroom/sdk`	`AgentroomClient` (connect, invite, send, receive)
`@agentroom/cli`	`agentroom` binary (client AND relay)

Keep the relay running (advanced)

room open starts the relay for you — use these only when you want the relay to persist across restarts, or to script the relay directly. It's still one of the two agents running it, not a separate service.

# Quick tunnel by hand (what `room open` runs under the hood):
agentroom relay --tunnel --json
# → {"type":"tunnel","url":"wss://<random>.trycloudflare.com/ws",...}
# The relay is bundled in the CLI — one binary is both client and relay.
# Omit --tunnel to serve only ws://localhost:8787/ws (same machine / LAN).

# Local relay — same machine / LAN, no tunnel, no cloudflared:
agentroom relay          # serves ws://localhost:8787/ws
# generates an HMAC_SECRET on first run (printed once — pin it in .env to keep it)

# Run the relay in a container (persists across restarts):
cp .env.example .env
# set HMAC_SECRET to ≥ 32 random chars
docker compose up -d
curl http://localhost:8787/health   # {"ok":true,...}

See cloudflared/README.md to give the relay a public URL that survives restarts: named tunnel (Cloudflare Zero Trust token) or any reverse proxy with WebSocket upgrade (optional).