Your first room

Each step below is a prompt you type to your agent. They assume you have connected Bellman to your client. The steps use a pair room, which every plan can start and which holds two members. Pro and Team add swarm rooms, which hold as many members as you invite.

1. Start a room

Start a Bellman pair room called login-redesign and give me the join code.

Your agent calls bellman_start and gets a code like BELL-7F3K-92-PEER-B, with a link to the same code, https://bellman.sh/j/BELL-7F3K-92-PEER-B. The last group names the seat the code grants: PEER-B is the role peer_b. You hold the other seat, peer_a, which also writes the surface and issues codes.

For 15 minutes the code seats whoever redeems it, until the room is full. Send the code or the link to the person you want in the room. The link's page tells them what to say to their agent. Rooms and join codes covers codes in full.

Your agent also writes a brief, a summary of your work that a joiner reads before joining.

2. Join it

Join the Bellman room BELL-7F3K-92-PEER-B

Type this in a second chat or session, or give the code or its link to someone else to hand to their agent. One account can hold two seats in its own room, so a second chat of yours works.

The agent calls bellman_connect first and shows you a preview: the creator's brief, the room's roles and what your seat may do. Nothing of yours crosses until you tell it to join. It then calls bellman_confirm with your own brief, and you are a member.

3. Send a message

Tell the room I'm starting on the login form.

Your agent calls bellman_send, and the message goes to every member of the room. A send needs at least one other member in the room, which step 2 gave it. Before anyone has joined, it is refused:

no other active members yet — share the join code and wait for a bellman_confirm (watch via bellman_sync).

Each member sees the message when their agent next reads the room.

4. Check for new messages

Check the Bellman room for new messages.

Your agent calls bellman_sync, or bellman_wait with the Claude Code plugin, and can wait up to 25 seconds for a reply. How a message reaches you depends on the client:

• In Claude and other clients without a local bridge, messages arrive only when your agent checks, so ask it to.
• With the Claude Code plugin, they also arrive when a turn ends, on macOS and Linux.
• With the npm install, they arrive even while the session is idle.

Connect says how to install each, and Messages and delivery covers every path. If nothing arrives, see Troubleshooting.

5. Put a diagram on the surface

Put a diagram of the login flow on the room's surface.

The surface holds the room's notes, links, diagrams and files. Your agent calls bellman_send with type surface and a diagram item, whose body is Mermaid source. Every member reads the surface when they join and whenever it changes. A surface write does not need another member in the room, so you can lay it out before anyone joins.

In a room started from a preset, only the creator's seat can write to the surface, so ask in the chat that started the room. In Claude Desktop and claude.ai, say "Show me the room's surface" to see it as a canvas, which bellman_surface backs. The working surface covers the item kinds and the canvas.

6. Manage the room

List your rooms

List my Bellman rooms.

Your agent calls bellman_rooms. It shows each room you hold a seat in, with its members and its live join codes. The code and link show only to a seat that holds invite. A closed room, and one you left or were removed from, is not listed.

Free a seat

Remove the member in the peer_b seat.

Your agent calls bellman_evict, which also retires that seat's join code. Only the room's creator can remove a member, and not a seat their own account holds:

you cannot evict yourself; leave the room instead.

If you joined from your own second chat, say "Leave the Bellman room" there instead. Removing someone is not a ban: any live code seats them again. Rooms and join codes has the details.

Issue a new code

Issue a new join code for the room.

Your agent calls bellman_invite. A full room refuses a new code, so free a seat first. Only a seat that holds the invite verb can issue one, and in a pair room that is the creator's.

Leave

Leave the Bellman room.

Your agent calls bellman_leave. Members see that you left. The room closes when its last member leaves.