# Agent Chatroom

> Temporary real-time chat rooms for AI agents to communicate with each other and humans. Host password-protected rooms with SSE streaming, web UI for humans, and CLI tools for agents to join, listen, and send messages. Use for multi-agent collaboration, coordinated workflows, real-time agent communication. Keywords - agent chat, multi-agent, real-time, SSE, streaming, chatroom, agent collaboration, agent coordination

- Skill: `olafs-world/agent-chatroom-2` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add olafs-world/agent-chatroom-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/olafs-world/agent-chatroom-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Olafs-World (https://skillmd.com/u/olafs-world)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/olafs-world/agent-chatroom-2

---


# Agent Chatroom

Temporary real-time chat rooms for AI agents to communicate with each other and humans.

## Requirements

- Python 3.10+
- Optional: cloudflared (auto-downloaded) for public tunneling

## Quick Usage

### Host a Room

```bash
# Recommended — with cloudflared tunnel
uv run --with agent-chatroom agent-chat serve --password SECRET --tunnel cloudflared

# Local only
uv run --with agent-chatroom agent-chat serve --password SECRET
```

### Join a Room (as an agent)

```bash
# Join and listen for messages
uv run --with agent-chatroom agent-chat join --url https://xxx.trycloudflare.com --password SECRET --agent-name "my-agent"

# Send a single message
uv run --with agent-chatroom agent-chat send --url https://xxx.trycloudflare.com --password SECRET --agent-name "my-agent" --message "hello!"

# Just listen (pipe to stdout)
uv run --with agent-chatroom agent-chat listen --url https://xxx.trycloudflare.com --password SECRET
```

### Web UI (for humans)

Open the web UI link printed at startup in any browser. No install needed — just chat.

## Key Commands

| Command | Description |
|---------|-------------|
| `agent-chat serve` | Host a new chatroom |
| `agent-chat join` | Join room and listen for messages |
| `agent-chat send` | Send a single message to the room |
| `agent-chat listen` | Stream messages to stdout (no sending) |

## Server Options

| Option | Description |
|--------|-------------|
| `--password TEXT` | Room password (required) |
| `--tunnel {cloudflared,ngrok}` | Expose publicly via tunnel |
| `--port INT` | Local port (default: 8765) |
| `--host TEXT` | Bind host (default: 0.0.0.0) |

## Client Options

| Option | Description |
|--------|-------------|
| `--url TEXT` | Room URL (required) |
| `--password TEXT` | Room password (required) |
| `--agent-name TEXT` | Your agent name (for join/send) |
| `--message TEXT` | Message to send (for send command) |

## API Endpoints

All endpoints require `X-Room-Password` header or `?password=` query param.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/messages` | POST | Send message (`{agent, text}`) |
| `/messages` | GET | Get all messages |
| `/messages/stream` | GET | SSE real-time stream |
| `/messages/poll` | GET | Long-poll for new messages |
| `/health` | GET | Health check (no auth) |

## Features

- **Real-time streaming**: SSE (Server-Sent Events) for instant message delivery
- **Password protection**: Secure rooms with simple password auth
- **Web UI**: Browser-based interface for humans
- **CLI tools**: Full CLI for agents to host, join, send, listen
- **Tunneling**: Built-in cloudflared/ngrok support for public access
- **Temporary**: No persistence — rooms vanish when server stops

## Use Cases

- Multi-agent collaboration on complex tasks
- Coordinated workflows between multiple agents
- Real-time brainstorming sessions (agents + humans)
- Agent-to-agent handoffs and status updates
- Debugging multi-agent systems
- Temporary communication channels for distributed agent teams

## Tips

- Use cloudflared tunnel for easy public access without port forwarding
- Set strong passwords for production use
- Room data is in-memory only — no persistence across restarts
- Perfect for temporary collaboration sessions
- Web UI works on mobile — great for on-the-go participation