room-cli 2.0.1

Multi-user chat room for agent/human coordination over Unix domain sockets
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# room-cli

Multi-user chat room for agent and human coordination over Unix domain sockets and WebSocket.

`room-cli` provides the `room` binary — a broker that manages chat rooms, a full-screen TUI for interactive use, and one-shot subcommands for scripting and AI agent integration.

## Installation

```bash
cargo install room-cli
```

The installed binary is named `room`.

## Quick start

```bash
# Terminal 1 — starts the broker and opens the TUI
room myroom alice

# Terminal 2 — joins the existing room
room myroom bob
```

The first invocation in a given room starts the broker automatically. Subsequent invocations connect as clients.

## Subcommands

| Command | Description |
|---------|-------------|
| `room <room-id> <username>` | Start or join a room (TUI mode) |
| `room join <room-id> <username>` | Register and get a session token |
| `room send <room-id> -t <token> <message>` | Send one message and exit |
| `room poll <room-id> -t <token>` | Print new messages as NDJSON and exit |
| `room watch <room-id> -t <token>` | Block until a message arrives, then exit |

## TUI features

- Full-screen terminal interface built with [ratatui](https://github.com/ratatui-org/ratatui)
- Version displayed in border, splash screen with tagline
- Slash commands: `/who`, `/dm <user> <msg>`, `/set_status <msg>`, `/claim <task>`
- Admin commands: `/kick`, `/reauth`, `/clear-tokens`, `/exit`, `/clear`
- Command palette with tab completion and `@` mention picker
- Multi-line input with `Shift+Enter`
- Message history scrolling with arrow keys / PageUp / PageDown

## Agent integration

For AI agents that use sequential tool calls (e.g. Claude Code):

```bash
# 1. Join once per broker session
room join myroom agent1
# → {"type":"token","token":"<uuid>","username":"agent1"}

# 2. Send messages
room send myroom -t <token> "starting work on #42"

# 3. Poll for new messages
room poll myroom -t <token>

# 4. Watch (block until a message arrives)
room watch myroom -t <token> --interval 5
```

See the [agent coordination protocol](../../CLAUDE.md) for the full multi-agent workflow.

## WebSocket / REST transport

Start the broker with `--ws-port` to enable HTTP access alongside Unix sockets:

```bash
room myroom alice --ws-port 4200
```

Endpoints:

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/<room>/join` | Register username, get token |
| `POST` | `/api/<room>/send` | Send a message (Bearer auth) |
| `GET` | `/api/<room>/poll` | Poll for messages (Bearer auth) |
| `GET` | `/api/health` | Health check |
| `ws://` | `/ws/<room>` | WebSocket connection |

## Documentation

- [Full CLI reference and wire format](../../README.md)
- [Agent coordination protocol](../../CLAUDE.md)
- [Ralph setup guide](../../docs/ralph-setup.md) — autonomous agent wrapper

## License

MIT